Copyright (c) 1980 The Regents of the University of California.
All rights reserved.

%sccs.include.redist.man%

@(#)puman5.n 6.3 (Berkeley) 04/17/91

.so tmac.p \} .ND .nr H1 4 Details on the components of the system Options

The programs

I ,

C , and .XP take a number of options.\*(dg .FS \*(dgAs uses

I to translate Pascal programs, it takes the options of

I also. We refer to them here, however, as

I options. .FE There is a standard X convention for passing options to programs on the command line, and this convention is followed by the P system programs. As we saw in the examples above, option related arguments consisted of the character `-' followed by a single character option name.

Except for the b option which takes a single digit value, each option may be set on (enabled) or off (disabled.) When an on/off valued option appears on the command line of

I or

X it inverts the default setting of that option. Thus .LS % \*bpi -l foo.p .LE enables the listing option l , since it defaults off, while .LS % \*bpi -t foo.p .LE disables the run time tests option t , since it defaults on.

In additon to inverting the default settings of

I options on the command line, it is also possible to control the

I options within the body of the program by using comments of a special form illustrated by .LS {$l-} .LE

Here we see that the opening comment delimiter (which could also be a `(*') is immediately followed by the character `$'. After this `$', which signals the start of the option list, we can place a sequence of letters and option controls, separated by `,' characters\*(dd. .FS \*(ddThis format was chosen because it is used by Pascal 6000-3.4. In general the options common to both implementations are controlled in the same way so that comment control in options is mostly portable. It is recommended, however, that only one control be put per comment for maximum portability, as the Pascal 6000-3.4 implementation will ignore controls after the first one which it does not recognize. .FE The most basic actions for options are to set them, thus .LS {$l+ Enable listing} .LE or to clear them .LS {$t-,p- No run-time tests, no post mortem analysis} .LE Notice that `+' always enables an option and `-' always disables it, no matter what the default is. Thus `-' has a different meaning in an option comment than it has on the command line. As shown in the examples, normal comment text may follow the option list. Options common to Pi, Pc, and Pix

The following options are common to both the compiler and the interpreter. With each option we give its default setting, the setting it would have if it appeared on the command line, and a sample command using the option. Most options are on/off valued, with the b option taking a single digit value.

Buffering of the file output - b

The b option controls the buffering of the file output . The default is line buffering, with flushing at each reference to the file input and under certain other circumstances detailed in section 5 below. Mentioning b on the command line, e.g. .LS % \*bpi -b assembler.p .LE causes standard output to be block buffered, where a block is some system-defined number of characters. The b option may also be controlled in comments. It, unique among the P options, takes a single digit value rather than an on or off setting. A value of 0, e.g. .LS {$b0} .LE causes the file output to be unbuffered. Any value 2 or greater causes block buffering and is equivalent to the flag on the command line. The option control comment setting b must precede the program statement.

Include file listing - i

The i option takes the name of an include file, procedure or function name and causes it to be listed while translating\*(dg. .FS \*(dg\*bInclude files are discussed in section 5.9. .FE Typical uses would be .LS % \*bpix -i scanner.i compiler.p .LE to make a listing of the routines in the file scanner.i, and .LS % \*bpix -i scanner compiler.p .LE to make a listing of only the routine scanner . This option is especially useful for conservation-minded programmers making partial program listings.

Make a listing - l

The l option enables a listing of the program. The l option defaults off. When specified on the command line, it causes a header line identifying the version of the translator in use and a line giving the modification time of the file being translated to appear before the actual program listing. The l option is pushed and popped by the i option at appropriate points in the program.

Standard Pascal only - s

The s option causes many of the features of the UNIX implementation which are not found in standard Pascal to be diagnosed as `s' warning errors. This option defaults off and is enabled when mentioned on the command line. Some of the features which are diagnosed are: non-standard procedure s and function s, extensions to the procedure write , and the padding of constant strings with blanks. In addition, all letters are mapped to lower case except in strings and characters so that the case of keywords and identifiers is effectively ignored. The s option is most useful when a program is to be transported, thus .LS % \*bpi -s isitstd.p .LE will produce warnings unless the program meets the standard.

Runtime tests - t and C

These options control the generation of tests that subrange variable values are within bounds at run time.

I defaults to generating tests and uses the option t to disable them.

C defaults to not generating tests, and uses the option C to enable them. Disabling runtime tests also causes assert statements to be treated as comments.\*(dd .FS \*(ddSee section A.1 for a description of assert statements. .FE

Suppress warning diagnostics - w

The w option, which defaults on, allows the translator to print a number of warnings about inconsistencies it finds in the input program. Turning this option off with a comment of the form .LS {$w-} .LE or on the command line .LS % \*bpi -w tryme.p .LE suppresses these usually useful diagnostics.

Generate counters for a pxp execution profile - z

The z option, which defaults off, enables the production of execution profiles. By specifying z on the command line, i.e. .LS % \*bpi -z foo.p .LE or by enabling it in a comment before the program statement causes

I and

C to insert operations in the interpreter code to count the number of times each statement was executed. An example of using .XP was given in section 2.6; its options are described in section 5.6. Note that the z option cannot be used on separately compiled programs. Options available in Pi

Post-mortem dump - p

The p option defaults on, and causes the runtime system to initiate a post-mortem backtrace when an error occurs. It also cause .X to count statements in the executing program, enforcing a statement limit to prevent infinite loops. Specifying p on the command line disables these checks and the ability to give this post-mortem analysis. It does make smaller and faster programs, however. It is also possible to control the p option in comments. To prevent the post-mortem backtrace on error, p must be off at the end of the program statement. Thus, the Pascal cross-reference program was translated with .LS % \*bpi -pbt pxref.p .LE Options available in Px

The first argument to .X is the name of the file containing the program to be interpreted. If no arguments are given, then the file obj is executed. If more arguments are given, they are available to the Pascal program by using the built-ins argc and argv as described in section 4.6.

Px may also be invoked automatically. In this case, whenever a Pascal object file name is given as a command, the command will be executed with .X prepended to it; that is .LS % \*bobj primes .LE will be converted to read .LS % \*bpx obj primes .LE Options available in Pc

Generate assembly language - S

The program is compiled and the assembly language output is left in file appended .s. Thus .LS % \*bpc -S foo.p .LE creates a file foo.s . No executable file is created.

Symbolic Debugger Information - g

The g option causes the compiler to generate information needed by sdb (1) the symbolic debugger. For a complete description of sdb see Volume 2c of the X Reference Manual.

Redirect the output file - o

The name argument after the -o is used as the name of the output file instead of a.out . Its typical use is to name the compiled program using the root of the file name. Thus: .LS % \*bpc -o myprog myprog.p .LE causes the compiled program to be called myprog .

Generate counters for a \*iprof execution profile - p

The compiler produces code which counts the number of times each routine is called. The profiling is based on a periodic sample taken by the system rather than by inline counters used by .XP . This results in less degradation in execution, at somewhat of a loss in accuracy. See prof (1) for a more complete description.

Run the object code optimizer - O

The output of the compiler is run through the object code optimizer. This provides an increase in compile time in exchange for a decrease in compiled code size and execution time. Options available in Pxp

Pxp takes, on its command line, a list of options followed by the program file name, which must end in `.p' as it must for

I ,

C , and . Pxp will produce an execution profile if any of the z , t or c options is specified on the command line. If none of these options is specified, then .XP functions as a program reformatter.

It is important to note that only the z and w options of .XP , which are common to

I ,

C , and .XP can be controlled in comments. All other options must be specified on the command line to have any effect.

The following options are relevant to profiling with .XP :

Include the bodies of all routines in the profile - a

Pxp normally suppresses printing the bodies of routines which were never executed, to make the profile more compact. This option forces all routine bodies to be printed.

Suppress declaration parts from a profile - d

Normally a profile includes declaration parts. Specifying d on the command line suppresses declaration parts.

Eliminate include directives - e

Normally, .XP preserves include directives to the output when reformatting a program, as though they were comments. Specifying -e causes the contents of the specified files to be reformatted into the output stream instead. This is an easy way to eliminate include directives, e.g. before transporting a program.

Fully parenthesize expressions - f

Normally .XP prints expressions with the minimal parenthesization necessary to preserve the structure of the input. This option causes pxp to fully parenthesize expressions. Thus the statement which prints as .LS d := a + b mod c / e .LE with minimal parenthesization, the default, will print as .LS d := a + ((b mod c) / e) .LE with the f option specified on the command line.

Left justify all procedures and functions - j

Normally, each procedure and function body is indented to reflect its static nesting depth. This option prevents this nesting and can be used if the indented output would be too wide.

Print a table summarizing procedure and function calls - t

The t option causes .XP to print a table summarizing the number of calls to each procedure and function in the program. It may be specified in combination with the z option, or separately.

Enable and control the profile - z

The z profile option is very similar to the i listing control option of

I . If z is specified on the command line, then all arguments up to the source file argument which ends in `.p' are taken to be the names of procedure s and function s or include files which are to be profiled. If this list is null, then the whole file is to be profiled. A typical command for extracting a profile of part of a large program would be .LS % \*bpxp -z test parser.i compiler.p .LE This specifies that profiles of the routines in the file parser.i and the routine test are to be made. Formatting programs using pxp

The program .XP can be used to reformat programs, by using a command of the form .LS % \*bpxp dirty.p > clean.p .LE Note that since the shell creates the output file `clean.p' before .XP executes, so `clean.p' and `dirty.p' must not be the same file.

Pxp automatically paragraphs the program, performing housekeeping chores such as comment alignment, and treating blank lines, lines containing exactly one blank and lines containing only a form-feed character as though they were comments, preserving their vertical spacing effect in the output. Pxp distinguishes between four kinds of comments:

Consider the following program. .LS % \*bcat comments.p .so comments1.p .LE When formatted by .XP the following output is produced. .LS % \*bpxp comments.p .so commentsout % .LE The following formatting related options are currently available in .XP . The options f and j described in the previous section may also be of interest.

Strip comments -s

The s option causes .XP to remove all comments from the input text.

Underline keywords - \_

A command line argument of the form -\_ as in .LS % \*bpxp -_ dirty.p .LE can be used to cause .XP to underline all keywords in the output for enhanced readability.

Specify indenting unit - [23456789]

The normal unit which .XP uses to indent a structure statement level is 4 spaces. By giving an argument of the form -d with d a digit, 2 \(<= d \(<= 9 you can specify that d spaces are to be used per level instead. Pxref

The cross-reference program pxref may be used to make cross-referenced listings of Pascal programs. To produce a cross-reference of the program in the file `foo.p' one can execute the command: .LS % \*bpxref foo.p .LE The cross-reference is, unfortunately, not block structured. Full details on pxref are given in its manual section pxref (1). Multi-file programs

A text inclusion facility is available with P . This facility allows the interpolation of source text from other files into the source stream of the translator. It can be used to divide large programs into more manageable pieces for ease in editing, listing, and maintenance.

The include facility is based on that of the UNIX C compiler. To trigger it you can place the character `#' in the first portion of a line and then, after an arbitrary number of blanks or tabs, the word `include' followed by a filename enclosed in single `\(aa' or double `"' quotation marks. The file name may be followed by a semicolon `;' if you wish to treat this as a pseudo-Pascal statement. The filenames of included files must end in `.i'. An example of the use of included files in a main program would be: .LS \*bprogram compiler(input, output, obj); #\*binclude "globals.i" #\*binclude "scanner.i" #\*binclude "parser.i" #\*binclude "semantics.i" \*bbegin { main program } \*bend. .LE

At the point the include pseudo-statement is encountered in the input, the lines from the included file are interpolated into the input stream. For the purposes of translation and runtime diagnostics and statement numbers in the listings and post-mortem backtraces, the lines in the included file are numbered from 1. Nested includes are possible up to 10 deep.

See the descriptions of the i option of

I in section 5.2 above; this can be used to control listing when include files are present.

When a non-trivial line is encountered in the source text after an include finishes, the `popped' filename is printed, in the same manner as above.

For the purposes of error diagnostics when not making a listing, the filename will be printed before each diagnostic if the current filename has changed since the last filename was printed. Separate Compilation with Pc

A separate compilation facility is provided with the Berkeley Pascal compiler,

C . This facility allows programs to be divided into a number of files and the pieces to be compiled individually, to be linked together at some later time. This is especially useful for large programs, where small changes would otherwise require time-consuming re-compilation of the entire program.

Normally,

C expects to be given entire Pascal programs. However, if given the -c option on the command line, it will accept a sequence of definitions and declarations, and compile them into a .o file, to be linked with a Pascal program at a later time. In order that procedures and functions be available across separately compiled files, they must be declared with the directive external . This directive is similar to the directive forward in that it must precede the resolution of the function or procedure, and formal parameters and function result types must be specified at the external declaration and may not be specified at the resolution.

Type checking is performed across separately compiled files. Since Pascal type defintions define unique types, any types which are shared between separately compiled files must be the same definition. This seemingly impossible problem is solved using a facility similar to the include facility discussed above. Definitions may be placed in files with the extension .h and the files included by separately compiled files. Each definition from a .h file defines a unique type, and all uses of a definition from the same .h file define the same type. Similarly, the facility is extended to allow the definition of const s and the declaration of label s, var s, and external function s and procedure s. Thus procedure s and function s which are used between separately compiled files must be declared external , and must be so declared in a .h file included by any file which calls or resolves the function or procedure . Conversely, function s and procedure s declared external may only be so declared in .h files. These files may be included only at the outermost level, and thus define or declare global objects. Note that since only external function and procedure declarations (and not resolutions) are allowed in .h files, statically nested function s and procedure s can not be declared external .

An example of the use of included .h files in a program would be: .LS \*bprogram compiler(input, output, obj); #\*binclude "globals.h" #\*binclude "scanner.h" #\*binclude "parser.h" #\*binclude "semantics.h" \*bbegin { main program } \*bend. .LE

This might include in the main program the definitions and declarations of all the global label s, const s, type s and var s from the file globals.h, and the external function and procedure declarations for each of the separately compiled files for the scanner, parser and semantics. The header file scanner.h would contain declarations of the form: .LS \*btype token = \*brecord { token fields } \*bend; \*bfunction scan(\*bvar inputfile: text): token; \*bexternal; .LE Then the scanner might be in a separately compiled file containing: .LS #\*binclude "globals.h" #\*binclude "scanner.h" \*bfunction scan; \*bbegin { scanner code } \*bend; .LE which includes the same global definitions and declarations and resolves the scanner functions and procedures declared external in the file scanner.h.