Heading:

Mesa 6.0 Utilities Update

Page Numbers: Yes X: 527 Y: 10.5"

Copyright c Xerox Corporation 1980

Inter-Office Memorandum

ToMesa UsersDateOctober 27, 1980

FromBrian Lewis, Jim Sandman, Dick SweetLocationPalo Alto

SubjectMesa 6.0 Utilities UpdateOrganizationSDD/SS/Mesa

XEROX

Filed on: [Iris]<Mesa>Doc>Utilities60.bravo (and .press)

This memo outlines the changes made in the utility packages since the last release (Mesa 5.0, April 9, 1979). More complete information can be found in the Mesa User’s Handbook.

Major changes include some new commands in the Lister and an extensively reworked IncludeChecker. In addition, there is a version of the SignalLister that reads .bcd files.

Lister

The lister is now available only as a .bcd file. The user interface has been changed slightly: commands that take string parameters no longer need string quotes. The command scanner takes all characters up to the next comma or right bracket as the parameter. Thus

Code[ListerRoutines] and Code["ListerRoutines"]

are equivalent. The new commands (and "improved" old ones) are listed below. Note that several of the new commands (and some of the old ones) are useful only for internal (Compiler) debugging.

CodeInConfig[config, module]
OctalCodeInConfig[config, module]

Config names a bound configuration; module is a module within that configuration. A code listing is produced for the module (see the Code and OctalCode commands). This is of particular interest for packaged configurations where the code has been rearranged among segments and code packs.

CompressUsing[file]

The named file should contain a list of BCD file names. The using lists of the directory statement are generated for each module in the list; they are then sorted to show for each interface, and for each item in the interface, which modules reference that item. The same caveat about implicitly included symbols applies as for the Using command (see below). The output is written to file.ul.

Hexify[], Octify[]

The code lister normally prints addresses (and opcodes for "octal" listings) in base eight. For microcode debugging, base sixteen is sometimes preferable. Hexify[] puts the code lister into hexadecimal mode; Octify[] reverts to octal mode.

Implementors[file]

The named file should contain a list of compiler output BCDs (interfaces and program modules). This command creates a file, File.iml, showing for each interface exported by any program in the list, where the various interface items are implemented. If the list also includes the BCD for a particular interface, the interface items not implemented by any program are also shown. In order to run this command, one needs not only the BCDs in the list, but also the BCDs for the interfaces exported by the programs therein. Missing BCDs are reported and the command attempts to forge on.

Stamps[file]

File names a compiler or binder output BCD. This command generates a file, File.bl, that shows the version stamps of any modules bound in the file, and of all imports and exports of the top level configuration in the file.

UnboundExports[file]

File names a compiler or binder output BCD. This command examines all of the exported interfaces and enumerates interface items in those interfaces that are not exported by this module or configuration.

Using[file]

Given a compiler output BCD, this command generates a directory statement with its included identifier lists (on file.ul). Since there is not enough information in the BCD to tell which symbols were implicitly included, the USING clauses will contain a superset of those items actually needed. The Mesa 6 Lister does a much better job of weeding out extraneous names in the USING clauses.

Version[file]

File names a compiler or binder output BCD, or an IMAGE file. This command shows, on Mesa.typescript, the object, source, and creator version stamps of the file.

XrefByCallee[file], XrefByCaller[file]

File names a file that contains a list of BCD file names. For each module in the list, a scan is made of the code to find all procedure calls. The <caller, callee> pairs are then sorted by either caller or callee. These commands produce output on file.xle and file.xlr, respectively.

There are three kinds of procedure calls: local, external, and stack. The program can figure out which procedure is being called for local and external calls. Stack function calls are used for procedure variables (e.g., stream.get[...]) and for nested procedure calls. The program ignores nested calls and indicates a callee of * for procedure variables.

Include Checker

The most significant differences between this version of the IncludeChecker and the one released with Mesa 5.0 are the following:

1.It handles more files, and requires less processing time for large numbers of files.

2.It executes either from the command line or interactively.

3.It obtains the creation dates for source files from their leader page, rather than from the first few lines of the source text (however, see the description of the new switch /t below).

There have been other minor changes to command syntax. The entire section of the Mesa User’s Handbook on the IncludeChecker is included below.

The IncludeChecker is a program that examines a collection of Mesa source and BCDs for consistency. It produces an output listing that gives a compilation order for the files, and for each BCD, a list of all the BCDs that it includes, and a list of the BCDs which include it. Any inconsistencies (which are described below) are flagged in this listing by an asterisk. As an option, the IncludeChecker will also generate a compilation command on Line.cm that can be executed to make the files consistent.

The IncludeChecker determines that an inconsistency exists among the input files if either:

1.A BCD includes another BCD with a version different from the one currently on the disk. This might happen, for example, if the included BCD had been recompiled.

2.A source file is "newer" than the corresponding BCD. This could happen if the source had been edited, or if the source had been retrieved from a remote file server. The IncludeChecker compares the creation date of the source file against the creation date recorded in the BCD of the source file from which the BCD was derived.

The IncludeChecker operates in either command line or interactive mode. To use it in command line mode, type to the Alto executive:

>IncludeChecker [outputfile][/switches] [filename1 filename2 ...]

where

outputfile is the name of the file written. If no extension or switches are given, .list is assumed. If no file name is specified, the file Includes.list is assumed.

filename1 filename2 . . . is the list of file names specifying the source and .bcd files to be checked. It is not necessary to give an extension, since the IncludeChecker will look for any .mesa or .bcd file with the specified name. If no input files are specified, all .mesa and .bcd files on the disk are examined.

To use the IncludeChecker interactively just type:

>IncludeChecker

It will then prompt for the output file name and switches, and then a list of the files to check. These are typed one at a time, and the list of file names is terminated by a CR. Typing ? CR in interactive mode displays a short summary of the IncludeChecker’s parameters and use.

Each switch can be preceded by a - or ~ to turn it off. The switches are:

/oPrint a compilation order in the output file (this is the default); -o suppresses this listing.

/iPrint both the includes and included by relationships in the output file (default).

/tObtain the creation date of source files from their leader page (default); -t will attempt to get the creation date from the first few lines of the source text.

/cWrite a consistent compilation command in Line.cm (-c is the default). In addition, list as comments any BCDs and source files not on the disk which are needed to do the compilation.

/mUse multiple output files (-m is default). The compilation order is written on source.outputfile. The includes and included by relations are written onto outputfile.includes and outputfile.includedBy, respectively. This switch is useful if the output would otherwise be too large to fit into Bravo.

/nDo not compile source files that do not currently have corresponding .bcds on the disk (-n is default).

/pPlace a /p after every change of inclusion depth (see below) in the compilation command (-p is default). This will cause the Compiler to pause if errors are found while compiling that or any previous module.

/sSame as /c-i-o. This is used when only a consistent compilation command is needed.

The default switches are /oit-c-m-n-p-s.

Note: The IncludeChecker only checks for consistency of the files that you specify. Thus, the list of files that you give should include, for example, any important system files upon which your files are dependent.

You should also inspect the compilation command before executing it, since the IncludeChecker’s idea of what should be recompiled may not be the same as yours.

If a source file but no BCD is found on the disk, the IncludeChecker outputs a warning on the display; in addition, it adds that file to the compilation command if /c and /-n are in effect. A warning is also displayed if a BCD is found that was created by an obsolete version of the Compiler; its source file is also added to the compilation command.

The IncludeChecker lists the file names of the compilation order and the consistent compilation command by inclusion depth, with the files that are the most deeply included first. Within that constraint, definitions modules are printed before program modules. In general, then, the "lowest level" definitions modules appear first, while the "highest level" program modules appear last.

As an example of the IncludeChecker’s use, the command line

>IncludeChecker IC/c IODefs IOPkg LexiconDefs Lexicon LexiconClient

will produce a consistent compilation command in Line.cm and the output shown below on IC.list.

Compilation Order (by inclusion depth):
LexiconDefs streamdefs stringdefs
IODefs
oldstringdefs systemdefs tty windowdefs
IOPkg Lexicon LexiconClient


IODefs (4-May-80 16:20:37 60#203#) (compilation source: 14-Apr-80 17:37:16) includes
streamdefs
stringdefs

IOPkg (28-May-80 9:30:01 60#203#) (compilation source: 28-May-80 9:08:43)
(source on disk: [same]) includes
IODefs (4-May-80 16:20:37 60#203#)
oldstringdefs
streamdefs
tty
windowdefs

Lexicon (28-May-80 9:30:29 60#203#) (compilation source: 28-Apr-80 17:02:20)
(source on disk: [same]) includes
IODefs (4-May-80 16:20:37 60#203#)
LexiconDefs (14-May-80 10:48:49 60#205#)
oldstringdefs
systemdefs

LexiconClient (28-May-80 10:02:50 60#203#) (compilation source: 28-May-80 10:02:14)
(source on disk: [same]) includes
IODefs (4-May-80 16:20:37 60#203#)
LexiconDefs (14-May-80 10:48:49 60#205#)
oldstringdefs

LexiconDefs (14-May-80 10:48:49 60#205#) (compilation source: 18-Apr-79 19:19:11)
(source on disk: [same]) includes nothing


IODefs is included by
IOPkg Lexicon
LexiconClient

IOPkg is included by nothing

Lexicon is included by nothing

LexiconClient is included by nothing

LexiconDefs is included by
Lexicon LexiconClient

BcdSignals

BcdSignals is an Alto/Mesa program which will produce a signal listing from a .bcd file; it works much like the Alto/Mesa SignalLister for listing the signals in a .image file (see the Mesa User’s Handbook). To produce the signal listing Foo.signals from Foo.bcd, type to the Alto Executive:

>BcdSignals [octalNumber/switch] Foo[/switches]

where

/ntakes octalNumber to be the global frame index of the first frame in this BCD. This will normally be the first free global frame index in the system into which the BCD will be loaded.

/xtakes octalNumber to be the StartPilot loadmap form of a global frame index. This is the number in brackets beside the module name in the loadmap. It should be 200B times the octal number used with the /n switch.

/plists the name, byte PC, and length of each procedure in Foo on Foo.procs.

/slist the signals of Foo on Foo.signals (default).

As usual, a - or ~ can be used to invert the sense of the /s switch.

Distribution:
Mesa Users
Mesa Group
SDSupport