CLU2C User’s Manual

Edition 1.0-draft-970206, for CLU2C Version 1.99

February 1997

Copyright © 1996, 1997 Department of Mathematical and Computing Sciences, Tokyo Institute of Technology. All rights reserved.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

1 Introduction

CLU2C is an implementation of the programming language CLU. More specifically, it is a CLU compiler with some basic library modules.

The basic strategy is to translate CLU to C. As you might be aware, the name CLU2C stands for ‘CLU to C’.

This manual does not describe CLU itself, although we assume you have some basic knowledge about CLU. See CLU Reference Manual for the language definition.

We use ‘CLU2C’ to denote the whole language system. We use clu2c to denote the compiler.

2 Basic Usage

The clu2c program translates CLU source files to the equivalent C source files. The resulting C source files are then compiled and linked by another program called clulink. This chapter describes the basic usage of these two programs.

We often refer to the clu2c program as the compiler and the clulink program as the linker in this chapter.

2.1 Getting Started

There are two executable programs named clu2c and clulink available to the user. Use clu2c for compiling CLU source files to get intermediate C source files. Then use clulink for compiling these intermediate C source files to get an executable file.

For example, a shell session that compiles a CLU source file named ‘hello.clu’ to get an executable file named ‘a.out’ might look like as follows:

% clu2c hello.clu
Creating DU specs from hello.clu
time = 0.010
Compiling hello.clu
time = 0.010
% clulink hello.c
creating hello.o
creating op-table.c
creating op-table.o
creating a.out
%

You can see several points from this simple example.

• By convention, source files written in CLU have a name with ‘clu’ as a suffix.
• The clu2c program takes names of CLU files as arguments.
• The clu2c program creates C files, whose name is the same as that of CLU file except that the suffix is replaced with ‘c’.
• The clulink program takes names of C files as arguments.
• The clulink program creates an executable program named ‘a.out’. (1)
• The clulink program creates auxiliary files, that is, object files that correspond to input C files, a C file named ‘op-table.c’, and an object file that corresponds to ‘op-table.c’.

You might want to rename ‘a.out’ as a more appropriate name, say ‘hello’. You can give ‘-o’ option to clulink for this purpose:

% clulink -o hello hello.c

This invocation of clulink creates an executable program named ‘hello’ instead of ‘a.out’.

2.2 Input Files

The compiler accepts several kinds of input files. At the minimum, you need to prepare one or more CLU source files. The other kinds of input files are optional. By convention, each kind of input files should have a specific suffix.

‘name.clu’

This is a CLU source file, which consists of one or more modules. The primary task of the compiler is to translate this file to an equivalent C source file named ‘name.c’.

‘name.equ’

This is an equate file, which consists of one or more equates. Equates in this file work as if they were placed at the beginning of the pseudo top-level scope that contains the entire source program. This top-level scope is special in the sense that identifiers introduced in it may be redefined in its nested scopes.

‘name.spc’

This is an interface specification file, which consists of one or more interface specifications. An interface specification is a module that suppresses all constructs that would not affect the interface of the abstraction the module would implement. In other words, it is something like a module but lacks the following constructs:

• declarations for own variables in procedures, iterators, and clusters
• statements in procedures, iterators, and cluster operations
• definitions for rep in clusters

Strictly speaking, such constructs are accepted but simply discarded. This file become needed when the compiler has no access to CLU source files that contain modules of which the compiler wants to know interfaces.

‘name.lib’

This is an interface specification library file. This is not a text file. Usually this file is created when clu2c is invoked with the -d option. This file may be used in order to collect interface specifications from CLU source files and interface specification files and arrange them into a single file.

2.3 Invoking clu2c

An invocation of clu2c has either of the following two forms:

clu2c [option…] input_spec…
clu2c [command_invocation…]

where ‘[a]’ means that a is optional and ‘a…’ means a sequence of one or more a’s. This section describes only the first form of invocations; description about the second form is deferred to Advanced Usage. For the time being, all you should know about the second form is that you can terminate clu2c by typing ‘quit’ when it is unintentionally invoked with no arguments.

2.3.1 Options for clu2c

The compiler recognizes the following options in the command line. Most options have both short forms (single hyphen followed by one character) and a long forms (double hyphens followed by option name). In this chapter options are generally referred in a short form only.

‘-c’

‘--compile-only’

Normally CLU source files specified in a command line undergo two stages of processes: extraction of interfaces and compilation. This option inhibits the first stage from taking place. This option may be used when the interfaces of the modules defined in the specified CLU source files are given to the compiler from other input files (i.e., interface specification files or interface specification library files).

‘-d file’

‘--dump=file’

The compiler gathers intefaces of the abstractions from various input files during processing them. This option causes these intefaces to be dumped, after all the compilation is completed, to the file specified by file as an interface specification library file. If file has no suffix, it specifies the file ‘file.lib’. This option corresponds to the dump command of the compiler

‘-F’

‘--force-code-generation’

Produce C source files even if any error is detected during compilation. This option is intended to be used by the developer and the use by the user is generally discouraged. This option corresponds to the allow command of the compiler

‘-f file’

‘--xfile=file’

Executes commands of the compiler in the file specified by file. If file has no suffix, the compiler first attempts to read the file ‘file.xfile’. This option corresponds to the xfile command of the compiler

‘-g’

‘--debug’

Produce debugging information and inlay it into the generated C source files. This information will be used by the debugger (We are developing a source-level CLU debugger called cludb, which is not yet publicly available). This option corresponds to the debug command of the compiler

‘-h’

‘--help’

Display a brief summary of the usage of the compiler. This option corresponds to the help command of the compiler

‘-M’

‘--make’

Run the compiler in the ‘make’ mode. In this mode, the compiler automatically detects CLU source files that need to be compiled in the working directory and compiles them. The compiler maintains three auxiliary files: ‘Depend’, ‘Location’, and ‘SPC.lib’. These files are created in the same directory where C source files are created. See … for more detail.

‘-n’

‘--dry-run’

Display the commands of the compiler that would be executed unless this option is specified.

‘-O’

‘--optimize[=mode]’

Specifies mode as an optimization mode. There are three optimization modes: false, time, and space. The optimization mode is set to false unless this option is specified. If mode is omitted, then time is assumed. This option corresponds to the optimize command of the compiler

‘-p’

‘--syntax-only’

Check the code for syntactic errors, and do not process any further.

‘-S’

‘--safe’

‘-s’

‘--spec-only’

Normally CLU source files specified in a command line undergo two stages of processes: extraction of interfaces and compilation. This option inhibits the second stage from taking place.

‘-t’

‘--type-check-only’

Check the code for syntactic and semantic errors, and do not process any further.

‘-x’

‘--externals’

Output cross-reference table for external names.

‘--char-version=number’

Tells the compiler that the version number of char will be used with the generated C files. This command is primarily for developers only.

‘--string-version=number’

Tells the compiler that the version number of string will be used with the generated C files. This command is primarily for developers only.

Some options are exclusive: you must not specify two or more among the ‘-p’ option, the ‘-s’ option, and the ‘-t’ option.

2.3.2 Specifying Input Files

You can specify input files by simply listing their names. For example, suppose that you have three CLU source files named ‘foo.clu’, ‘bar.clu’, and ‘baz.clu’ in the current working directory. You can directly specify these files by listing their names as:

foo.clu bar.clu baz.clu

Generally speaking, the compiler receives a list of input specifications. An input specification is either a file specification or an indirect specification. A file specification is a file name except that ‘*’ is treated as a wild card character as in most shells. An indirect specification is ‘@’ followed by a file name. The named file must contain input specifications, one for each line. In either case, an input specification expands to a list of file names.

Default Suffix

There is a default suffix specific to the context where input specifications are interpreted. Any input file name with a default suffix can be specified without a suffix. When an input specification does not have a suffix apparently, a file name derived by appending a default suffix is tried first. If such a file exists, the specification is interpreted as specifying this file; otherwise it is treated as is with respect to the suffix.

The default suffix is ‘clu’ for input specifications in a shell command line that invokes clu2c, except for file names in indirect specifications. For example, when clu2c is invoked as

clu2c foo

then the compiler first checks if ‘foo.clu’ exists. If it does, the compiler reads ‘foo.clu’; otherwise it reads ‘foo’.

Globbing Input Files

The ‘*’ character is treated as a meta-character that matches zero or more sequence of any characters, as in most shells. Although your shell probably expands ‘*’ in a shell command line by itself, the compiler expands ‘*’ wherever an input specification is expected.

For example, you can specify all CLU source files in the current working directory as:

*.clu

Indirect Specifications

You can specify input files indirectly through a file. If an input specification begins with ‘@’, the rest of the specification is treated as specifying a file that contains a list of input specifications, one specification per line. The default suffix for this file, sometimes called a ‘response file’, is ‘xload’.

Note that each line in this file is not just a file name but an input specification: the default suffix and file name globbing still work.

For example, suppose you have a file named ‘sources.xload’ that consists of the following three lines:

foo.clu
bar.clu
baz.clu

Then the specification

@sources.xload

is completely equivalent to the following input specifications

foo.clu bar.clu baz.clu

The default suffix for a file that follows ‘@’ is ‘xload’. Thus you can also specify as:

@sources

2.4 Compiler Behavior

Normally CLU source files undergo two stages of processes. In the first stage, interface specifications are extracted; in the second stage, code generation takes place. Some options change this behavior. If you specify the -t option, the second stage stops when type-checking and some other validity-checking have been completed. If you specify the -s option, the second stage is not performed. If you specify the -p option, only syntactic validity is checked. If you specify one of these options, no code is generated.

Equate files are …

Interface specification files are …

Interface specification library files are …

2.5 Invoking clulink

The clulink program recognizes the following options to control how it operates:

‘-V’

‘--version’

Print the version of clulink.

‘-g’

‘--debug’

Generate debugging information, as in the C compiler.

‘-h’

‘--help’

Print the brief description of the usage.

‘-v’

‘--verbose’

Print additional messages.

‘-o file’

‘--output=file’

Specify the name of the output file.

‘-Ldirectory’

‘--libdir=directory’

Append directory to the library search path.

‘-lname’

‘--lib=name’

Link an archive associated with name.

‘-c compiler’

‘--cc=compiler’

Use compiler as a C compiler.

‘-F flag’

‘--cc-flag=flag’

Pass flag to the C compiler.

‘-P plink’

‘--plink=plink’

Use plink as a pre-linker.

‘-f’

‘--force’

Force compilation.

3 Advanced Usage

(This chapter may be skipped initially.)

As a matter of fact, clu2c is a command interpreter. The user might be unaware of this fact so long as (s)he uses clu2c through the command line interface, and it is sufficient in most situations. Sometimes, however, it may be necessary to control the compiler more closely by issuing a sequence of commands.

There are two ways to give commands directly to the compiler. First, the compiler reads commands from the standard input if it is invoked without arguments. Secondly, if the compiler is invoked with the -f option, it reads commands from the specified file.

In order to know how to use commands for clu2c, you need to understand the compiler’s internal architecture to some extent, especially the compilation environment and the interface specification library.

3.1 Command Syntax

A command invocation has a form:

command_name [ argument… ]

where [ x ] means an optional x and x… means one or more sequence of x. The number and the kind of the arguments depend on which command is invoked. command_name is case-insensitive and can be specified with an unambiguous prefix.

Some commands take a boolean value as an argument. Specify ‘true’ or ‘false’. This is again case-insensitive and can be specified with an unambiguous prefix.

Some commands take a list of input specifications as arguments. In the description of such commands, input_spec is used. See section Specifying Input Files, for syntax and semantics of input specifications.

You can specify two or more commands, separated by semicolons, in one line. For example, to specify specs and compile commands in one line, do like this:

specs foo.clu; compile foo.clu

You can use a sharp sign (‘#’) instead of a semicolon for backward compatibility.

3.2 Compiler Invocation Revisited

When the compiler is invoked with arguments, it first converts them into a sequence of command invocations and then executes them in order.

For example, suppose clu2c is invoked as follows:

clu2c -s -d foo foo.lib foo.clu bar.clu baz.clu

Then, clu2c converts the command line arguments into the following command sequence and executes them in order.

merge foo.lib
specs foo.clu bar.clu baz.clu
dump foo.lib

3.2.1 Options Conversion

The -n option lets the compiler show what commands would be executed but do not actually execute them. This option can be used to see how command line arguments are converted to a sequence of command invocations. The -p option, the -s option, and the -t option change the compiler’s behavior with respect to what kind of command(s) are applied to input files (see below). The other options are converted to commands directly:

• ‘-c’ is converted to ‘expunge true’.
• ‘-g’ is converted to ‘debug true’.
• ‘-d file’ is converted to ‘dump file’.
• ‘-x’ is converted to ‘externals true’.
• ‘-F’ is converted to ‘allow true’.
• ‘-Omode’ is converted to ‘optimize mode’.
• ‘-f file’ is converted to ‘xfile file’.

3.2.2 Input Files Conversion

Input files are grouped on the per-suffix basis. Then one or two commands are applied to each group.

• Normally the specs and compile commands are applied to CLU source files. If the -t option is specified, the check command is applied instead of compile. If the -s option is specified, the specs command only is applied. If the -p option is specified, the parse command only is applied.
• To equate files, the ce command is applied to the first group and xce to the subsequent groups.
• Normally the ‘specs’ command is applied to interface specification files. If the -p option is specified, the parse command is applied instead.
• To interface specification library files, the merge command is applied.

3.3 Compilation Environment

The clu2c program maintains a set of equates called compilation environment or CE for short. The compiler process starts with an empty CE. Then the user can append equates to the CE using ce and xce commands.

When the compiler detects a free identifier, i.e., identifier that is used but not declared nor defined in the module to be compiled, it first looks up the equate that defines the identifier in the CE. If such an equate is found, right hand side of the equate is used as a value of the identifier.

The following commands are provided as operations on CE. The default suffix for input files is ‘equ’.

Command: ce input_spec…

Discard all the equates in the current CE and use the set of equates described in the input files as a new CE.

Command: xce input_spec…

Add equates described in the input files to the current CE.

3.4 Interface Specification Library

In order to type-check a module, interface specifications of all the abstractions that are referred by the module must be known. The compiler has an internal table for storing interface specifications of abstractions. We call this table interface specification library.

Initially, interface specifications of built-in types and type generators, together with standard I/O abstractions, are registered in the interface specification library.

The following commands are provided as operations on the interface specification library.

Command: specs input_spec…

Extracts interface specifications from input files, and enters these specifications in the specification library. The default suffix is ‘spc’ or ‘clu’.

Command: dump filename

Dumps the content of the specification library to the file named filename. The default suffix is ‘lib’.

Command: merge input_spec…

Reads interface specifications from the input files, which is previously dumped using the dump command, and merges them into the specification library. The default suffix for input files is ‘lib’.

Command: unmerge input_spec…

Reads interface specifications from the input files, which is previously dumped using the dump command, and deletes the interface specifications for these modules. The default suffix for input files is ‘lib’.

Command: forget module…

Deletes the interface specification of module from the specification library.

Command: newlib

Resets the specification library to its initial state.

3.5 Compilation Commands

Command: compile input_spec…

Command: clu input_spec…

Produces binary output. A binary file is produced only if there are no errors. Hence, if a binary file is produced, any messages are warnings, not errors.

Command: check input_spec…

Does type- and legality- checking.

Command: parse input_spec…

Just parses the files, checking for syntactic errors.

3.6 Changing Code Generator’s Behavior

Command: allow [boolean]

If boolean implies ‘true’, the subsequent invocations of the compile command always produce (maybe incomplete) C source files even if any error is detected. If ‘false’ is implied, this behavior is canceled. This command is intended to be used by the developer and the use by the user is discouraged.

Command: binsuf [suffix]

Sets the suffix for binary files. The default is ‘c’. If no argument is given, resets to the default. If ‘*’ is given, no suffix will be used. This is useful when creating library binaries.

Command: char-version number

Tells the compiler that the version number of char will be used with the generated C files. This command is primarily for developers only.

Command: debug [boolean]

Command: optimize [time|space|false]

If no argument is specified, the default is time. The optimization mode affects all subsequent compilations. space causes only optimizations that do not increase the code size. time additionally performs optimizations that can increase the code size. Optimization eliminates many traceable routine calls, and so should only be used on well-debugged programs. See also the locals command.

Command: safe [boolean]

In safe mode, each module to be compiled is checked to make sure its name does not clash with an existing module name in the CLU system. This is done by looking in the file ~CLU/system.names. The initial mode is false.

Command: string-version number

Tells the compiler that the version number of string will be used with the generated C files. This command is primarily for developers only.

3.7 Miscellaneous Commands

This subsection describes miscellaneous commands not described in the above subsections.

Command: expunge [boolean]

In expunge mode, only the interfaces of clusters are remembered; the interfaces of external routines are not.

Command: externals [boolean]

The compiler normally outputs a cross-reference of references to external modules. This command can be used to stop that output.

Command: force [boolean]

This command is recognized for backward compatibility but no longer has any effect.

Command: help

Command: ?

Prints a brief summary of the commands.

Command: locals [boolean]

This command is recognized for backward compatibility but no longer has any effect.

Command: quit

Command: kill

Terminates the compiler process.

Command: xfile input_spec…

Reads a list of commands from input files and executes them in order. The default suffix for input files is ‘xfile’.

3.8 Invoking plink

The plink program is a pre-linker for C files which are generated by clu2c. It has two modes: normal mode and extraction mode. In normal mode, plink reads C files generated by clu2c and produces an auxiliary C file which contains various variable/function definitions that cannot be fixed until all the C files are prepared. In extraction mode, plink extracts C comments related to plink from the specified C files, which may be the input for later plink execution. plink is invoked through the clulink program. Users rarely invoke plink directly. The plink program recognizes the following options.

‘-o file’

Produces an output C source file by the name file. The name of the default object file is ‘op-table.c’ in normal mode; put to standard output by default in extraction mode.

‘-x’

Executes plink in extraction mode. In this mode, plink extracts, from input files, C comments that make sense for plink.

4 Changes to CLU

4.1 Lexical Changes

A particular subset of JIS X0208 is permitted in tokens and separators.

Some characters defined in JIS X0208 are conceptually equivalent to those in ASCII (see the table below). Such characters are not distinguished in source code except for char and string literals, excluding surrounding quotes.

====================================
ASCII   JIS X0208 equivalent (kuten)
------------------------------------
SP      1-1
!       1-10
"       1-41
#       1-84
$       1-80
%       1-83
&       1-85
'       1-39
(       1-42
)       1-43
*       1-86
+       1-60
,       1-4
-       1-61
.       1-5
/       1-31
0...9   3-16...3-25
:       1-7
;       1-8
<       1-67
=       1-65
>       1-68
?       1-9
@       1-87
A...Z   3-33...3-58
[       1-46
\       1-79
]       1-47
^       1-16
_       1-18
`       1-38
a...z   3-65...3-90
{       1-48
|       1-35
}       1-49
~       1-17
------------------------------------

An identifier can contain JIS X0208 ‘hiragana’, ‘katakana’, ‘kanji’, Greek letters, Cyrillic letters, and special characters in the following table.

=================================================
Kuten   Description
-------------------------------------------------
1-11    `dakuten'
1-12    `han-dakuten'
1-19    `katakana' repetition symbol
1-20    `katakana' repetition symbol (`dakuten')
1-21    `hiragana' repetition symbol
1-22    `hiragana' repetition symbol (`dakuten')
1-25    repetition symbol
1-28    `cho-on' symbol
-------------------------------------------------

Comments can contain any JIS X0208 characters.

A new punctuation symbol ‘!’ can be used.

A new escape sequence of the form \xhhhh can be used.

Operation on char: width = proc (c: char) returns (int)

effects Returns the minimum number of bytes required to represent c.

Operation on string: width = proc (s: string) returns (int)

effects This operation is equivalent to the following:

width = proc (s: string) returns (int)
    w: int := 0
    for c: char in string$chars (s) do
        w := w + char$width (c)
    end
    return (w)
end width

Operation on stream: set_code = proc (s: stream, code: string) signals (not_possible (string))

modifies s
effects Changes the coding system for s to code.

Operation on stream: get_code = proc (s: stream) returns (string) signals (not_possible (string))

effects Returns the coding system for s.

4.2 Start-up Procedure

The definition of CLU does not specify how program execution begins. In CLU2C, program execution begins by invoking a procedure named start_up. This procedure is called the start-up procedure. There is no way to use another name for it. It is up to the programmer to implement the start-up procedure. It must have the following heading:

start_up = proc ()

That is, it takes no arguments and terminates in either of:

• the normal condition with no results.
• the failure condition with a string result.

When start_up signals the failure exception, the run-time system attempts to print the result to the standard error before it terminates the program execution.

4.3 Object-Oriented Invocation

An object-oriented invocation has the following two forms:

primary!name [()]
primary!name (expression, …)

These forms are just syntactic sugar for an operation invocation and are completely equivalent to (respectively):

T$name (primary)
T$name (primary, expression, …)

where T is the type of primary. For example, if a is an array of integers, then

a!addh (1)

is completely equivalent to the invocation

array[int]$addh (a, 1)

Note that they are syntactic sugar: they by no means enable dynamic dispatching of operations. Remember that CLU is an almost statically-typed language.

4.4 Failure Result

According to the definition of CLU, an exception not handled in a routine becomes

failure ("unhandled exception: exception_name")

where exception_name is the name of the unhandled exception. In CLU2C, this transformation is slightly modified: the unhandled exception named exception_name becomes

failure ("unhandled exception: exception_name in routine_name")

where routine_name is the name of the routine that did not handle the exception. This will help you find where the problem is. Similarly, if a procedure that should return results in the normal condition reaches the textual end of its body, it signals

failure ("no return values in procedure_name")

rather than

failure ("no return values")

where procedure_name is the name of the procedure.

This modification is canceled when you compile source code in optimization mode.

4.5 Notes on File Names

Implementation of file_name is dependent on the target file system. CLU2C provides two implementations for file_name: one for UNIX file system, and the other for MS-DOS file system. It is determined at installation-time which implementation is available to the user.

This chapter describes some details about file names not described in CLU Reference Manual and specific to CLU2C.

4.5.1 File Name Components

In terms of file_name, file names are viewed as consisting of four string components: directory, name, suffix, and other. In CLU2C, any component may be empty.

• The name component cannot contain any path delimiters.
• The suffix component must be empty if the name component is empty.
• The suffix component cannot contain any path delimiters nor any periods.
• The other component must be empty.

On UNIX systems,

• The path delimiter is a slash character (‘/’).

On MS-DOS systems,

• The path delimiter is a backslash character (‘\’). The file_name$create and file_name$parse also interprets a slash character as a path delimiter (this seems to be a common convention).
• The directory component may start with a drive specification, i.e., drive name (from ‘a’ to ‘z’) followed by a colon. We refer to the rest of the directory component after the drive specification as a proper directory. For example, suppose the directory component of a file name is ‘c:\bin\clu2c’. In this case, the drive specification is ‘c:’ and the proper directory is ‘\bin\clu2c’.
• Upper and lower case letters are not distinguished in any components. The file_name$create and file_name$parse operations convert ASCII uppercase letters into corresponding ASCII lowercase letters,

4.5.2 Parsing Strings as File Names

The file_name$parse operation parses the given string argument and creates a file name. The primary task of this operation is to split the argument into four components (actually three, since the other component is always empty).

1. Splits the given string to the directory component and a non-directory. If the string contains any path delimiters, the last path delimiter splits it into them; otherwise directory is empty and the whole string is non-directory.
2. The name of the directory entry is split into the name and suffix components with a period such that the adjacent two characters do exist and both are not periods.

Tilde notations for specifying home directory work. Especially, ‘~CLU’ denotes the CLU2C system root directory (typically ‘/usr/local/lib/clu2c’).

Here are some examples, where resulting file name objects are written in the form of {directory, name, suffix, other}:

file_name$parse("/")
    ⇒ {"/", "", "", ""}
file_name$parse(".cshrc")
    ⇒ {"", ".cshrc", "", ""}
file_name$parse("/usr/local/src/clu2c.tar.gz")
    ⇒ {"/usr/local/src", "clu2c.tar", "gz", ""}

5 Library Abstractions

5.1 Directory Entries

You can merge ‘~CLU/lib/dirent.lib’ to get the interface specifications of the abstractions described in this section.

Routine: directory_entry_names = iter (dir: file_name) yields (string) signals (not_possible (string))

effects Yields names of the entry in dir in an arbitrary order.

5.2 File Operations

You can merge ‘~CLU/lib/file.lib’ to get the interface specifications of the abstractions described in this section.

5.2.1 Distinguishing Kinds of Files

Routine: file_is_block_device = proc (fn: file_name) returns (bool)

effects Returns true if a file named fn exists and it is a block device; otherwise returns false.

Routine: file_is_character_device = proc (fn: file_name) returns (bool)

effects Returns true if a file named fn exists and it is a character device; otherwise returns false.

Routine: file_is_directory = proc (fn: file_name) returns (bool)

effects Returns true if a file named fn exists and it is a directory; otherwise returns false.

Routine: file_is_fifo = proc (fn: file_name) returns (bool)

effects Returns true if a file named fn exists and it is a fifo (i.e., named pipe); otherwise returns false.

Routine: file_is_regular = proc (fn: file_name) returns (bool)

effects Returns true if a file named fn exists and it is a regular file; otherwise returns false.

Routine: file_is_symbolic_link = proc (fn: file_name) returns (bool)

effects Returns true if a file named fn exists and it is a symbolic link; otherwise returns false.

5.3 File Name Handling

You can merge ‘~CLU/lib/filename.lib’ to get interface specifications of the abstractions described in this section.

5.3.1 Accessing File Name Components

Routine: file_name_nondirectory = proc (fn: file_name) returns (string)

effects This procedure is equivalent to the following:

file_name_nondirectory = proc(fn: fname) returns(string)
    fname = file_name
    entry: fname := fname$create("", fn.name, fn.suffix, fn.other)
    return(fname$unparse(entry))
end file_name_nondirectory

This procedure transforms fn in a string representation like file_name$unparse as if the directory component of fn was empty.

Routine: file_name_drive = proc (fn: file_name) returns (string)

effects On UNIX this procedure returns an empty string. On MS-DOS this procedure returns a drive specification in the directory component of fn if it exists; otherwise returns an empty string.

Routine: file_name_proper_directory = proc (fn: file_name) returns (string)

effects On UNIX this procedure is equivalent to file_name$get_dir. On MS-DOS

5.3.2 Transforming File Names

Routine: file_name_fill_directory = proc (fn: file_name) returns (file_name)

effects This procedure fills in or fixes up the directory component of fn if it is empty or relative; otherwise merely returns fn. The result may or may not be absolute. If the result is not absolute, it will be treated as relative to the current working directory associated with the current process.

Routine: file_name_fill_suffix = proc (fn: file_name, suffix: string) returns (file_name)

effects If the suffix component of fn is empty and suffix is valid as a suffix component, an invocation of this procedure is equivalent to the following invocation:

file_name$create(fn.dir, fn.name, suffix, fn.other)

Otherwise simply returns fn.

Routine: file_name_apply_directory = proc (fn, base: file_name) returns (file_name)

effects

Routine: file_name_absolutize = proc (fn: file_name) returns (file_name)

effects

Routine: file_name_is_absolute = proc (fn: file_name) returns (bool)

effects Returns true if fn represents an absolute file name; otherwise returns false.

Routine: file_name_simplify = proc (fn: file_name) returns (file_name)

effects

Routine: file_name_expand_home_directory = proc (fn: file_name) returns (file_name)

effects

Directory names are file names such that all the components other than directory are empty.

Routine: file_name_as_directory = proc (fn: file_name) returns (file_name)

effects

Routine: directory_file_name = proc (fn: file_name) returns (file_name)

effects

5.3.3 Specific File Names

Routine: current_directory = proc () returns (file_name)

effects Returns the current working directory associated with the currently executing process.

Routine: home_directory = proc (user: string) returns (file_name) signals (not_found)

effects Returns user’s home directory if it can be determined; otherwise signals not_found. An empty user implies the user associated with the currently executing process. The "CLU" user is treated as to have the CLU system root directory as its home directory. The result is a directory name, i.e., all the components other than directory are empty.

5.4 Integer Handling

This section describes some auxiliary operations on int. You can merge ‘~CLU/lib/int.lib’ to get interface specifications of the abstractions described in this section.

Routine: int_hex_parse = proc (s: string) returns (int) signals (bad_format, overflow)

effects Equivalent to int$parse except that each digit in s shall be hexadecimal. The letters from ‘a’ (or ‘A’) through ‘f’ (or ‘F’) are used as hexadecimal digits with values from 10 through 15, respectively.

Routine: int_hex_unparse = proc (i: int) returns (string)

effects Equivalent to int$unparse except that each digit in the result is hexadecimal. The letters from ‘a’ through ‘f’ are used for hexadecimal digits with values from 10 to 15, respectively.

Routine: int_oct_parse = proc (s: string) returns (int) signals (bad_format, overflow)

effects Equivalent to int$parse except that each digit in s shall be octal.

Routine: int_oct_unparse = proc (i: int) returns (string)

effects Equivalent to int$unparse except that each digit in the result is octal.

5.5 Mathematical Functions

The overflow exception occurs if the magnitude of the result is greater than Real_Max, unless otherwise specified. The underflow exception occurs if the magnitude of the result is less than Real_Min, unless otherwise specified.

Interface specifications of these functions are contained in ‘~CLU/lib/math.spc’.

5.5.1 Trigonometric Functions

In the following descriptions, ‘PI’ denotes the ratio of the circumference of a circle to its diameter.

Routine: acos = proc (x: real) returns (real) signals (bounds, overflow)

effects Signals bounds if x is less than -1 or greater than 1; otherwise returns the arc cosine of x in the range [0, PI] radians.

Routine: asin = proc (x: real) returns (real) signals (bounds, underflow)

effects Signals bounds if x is less than -1 or greater than 1; otherwise returns the arc sine of x in the range [-PI/2, +PI/2] radians.

Routine: atan = proc (x: real) returns (real) signals (underflow)

effects Returns the arc tangent of x in the range [-PI/2, +PI/2] radians.

Routine: atan2 = proc (y, x: real) returns (real) signals (undefined, underflow)

effects Signals undefined if both x and y are zero; otherwise returns the arc tangent of y/x in the range [-PI, +PI] radians.

Routine: cos = proc (x: real) returns (real) signals (underflow)

effects Returns the cosine of x (measured in radians).

Routine: sin = proc (x: real) returns (real) signals (underflow)

effects Returns the sine of x (measured in radians).

Routine: tan = proc (x: real) returns (real) signals (overflow, underflow)

effects Returns the tangent of x (measured in radians).

5.5.2 Hyperbolic Functions

Routine: cosh = proc (x: real) returns (real) signals (overflow, underflow)

effects Returns the hyperbolic cosine of x.

Routine: sinh = proc (x: real) returns (real) signals (overflow, underflow)

effects Returns the hyperbolic sine of x.

Routine: tanh = proc (x: real) returns (real) signals (underflow)

effects Returns the hyperbolic tangent of x.

5.5.3 Exponential and Logarithmic Functions

Routine: exp = proc (x: real) returns (real) signals (overflow, underflow)

effects Returns the exponential function of x.

Routine: log = proc (x: real) returns (real) signals (complex_result, undefined, overflow, underflow)

effects Signals complex_result if x is negative; signals undefined if x is zero; otherwise returns the natural logarithm of x.

Routine: log10 = proc (x: real) returns (real) signals (complex_result, undefined, overflow, underflow)

effects Signals complex_result if x is negative; signals undefined if x is zero; otherwise returns the base-ten logarithm of x.

5.5.4 Power Functions

Note that a general power function is implemented as the real$power operation.

Routine: sqrt = proc (x: real) returns (real) signals (complex_result, overflow, underflow)

effects Signals complex_result if x is negative; otherwise returns the square root of x.

5.6 Program Environment

You can merge ‘~CLU/lib/progenv.lib’ to get interface specifications of the abstractions described in this section.

5.6.1 Argument Vector

Routine: program_name = proc () returns (string)

effects Returns the program name associated with the current process.

Routine: program_arguments = proc () returns (sequence[string])

effects Returns the program arguments associated with the current process.

Routine: input_streams = iter (inputs: sequence[string]) yields (stream)

effects Yields the primary input stream if inputs is empty (the primary input stream is the stream returned by the stream$primary_input operation). Otherwise yields an input stream specified by each element of inputs, in order. If an element of inputs is ‘-’, it specifies the primary input stream. Any other elements specify input streams that result from opening files named by those elements. If a named file cannot be opened, prints an error message to the primary output stream for error messages (returned by the stream$error_output operation) and yields nothing as far as that element of inputs is concerned.

5.6.2 Option Handling

Data type: getopt = data type is create, create_long, options, get_optname, get_optarg, optarg_is_empty, optarg_is_full, get_optind, get_opterr, set_opterr, set_output, get_non_options, non_options

Overview

The getopt type provides the means to analyze the argument vector (sometimes called an argv) supplied to a program when it was invoked.

From the point of view of getopt, an argument vector consists of zero or more option arguments followed by zero or more non-option arguments. Option arguments specify a set of options. An option can take an argument for itself.

The argument that starts with a minus sign (-) followed by one or more characters is an option argument unless otherwise specified. It specifies one or more options. If an option specified by an option argument takes an argument and an argument to the option is not specified in the option argument, the next argument in the argument vector is taken as an argument to the option.

At the minimum, an option argument consists of a minus sign followed by a single character (e.g., -a), which specifies a single option. If an option takes an argument, the argument to the option can be specified in the same option argument. For example, suppose that the -o option takes an argument. The argument to this option, say foo, can be specified as -ofoo, as well as -o foo, as mentioned above.

Options specified by a single character can be grouped into a single option argument. For example, the three options -a, -b, and -c can be specified as -abc. Note that an argument-taking option eats up an option argument. For example, if the -o option takes an argument as before, the option argument -aobc is equivalent to the tree option arguments -a -o bc.

An getopt object can be made tailored to recognize long-form options (in contrast to short-form options described so far). The form of an long-form option is

--name[=argument]

where name can be specified with an unambiguous prefix.

A special option argument that consists of two minus signs (i.e., --), unless taken as an argument for the preceding option, does not modify the program behavior but modifies the way the argument vector is analyzed: it specifies the end of option arguments. That is, all the arguments that follows this argument are taken as non-option arguments, even if they start with a minus sign.

An getopt object is mutable. The state of an getopt object changes during the execution of the options operation. No other operations change the state. Each time the options operation yields, it sets the current option to the yielded one.

Operations

Operation on getopt: create = proc (argv: sequence[string], optstring: string) returns (getopt) signals (bad_format)

effects Returns a new getopt object that analyzes short-form options in argv. The legitimate characters for the options are listed in optstring. If a character is followed by a colon (:), the option specified by the character takes an argument. The other options does not take an argument. Signals bad_format if optstring is empty or it starts with a colon.

Operation on getopt: create_long = proc (argv: sequence[string], shortopts: string, longopts: long_option_list) returns (getopt) signals (bad_format)
long_option_list = sequence[long_option]
long_option = struct[name: string, arg: int, val: char]
no_argument = 0
required_argument = 1
optional_argument = 2

effects Returns a new getopt object that analyzes short-form options as well as long-form options in argv. The shortopts argument is the same as optstring for create except that it can be empty, in this case only long-form options are analyzed. The longopts argument specifies a set of legitimate long-form options. Each element specifies a single long-form option. The name component is the name of the option. The arg component specifies whether the option takes an argument: no_argument means that the option does not take an argument; required_argument means that the option takes an argument; optional_argument means that the option takes an argument but the argument can be omitted. The val component specifies the character yielded by the options operation when the option is encountered. Signals bad_format if shortops starts with a colon or longopts is not in the form mentioned above.

Operation on getopt: options = iter (go: getopt) yields (char)

requires The options operation has not been invoked on go.
modifies go.
effects Analyzes the argument vector and yields a character that corresponds to the option encountered. If the option is in short form, yields the character that specifies the option. If the option is in long form, yields the val component that corresponds to the option. If the specified option is not legitimate, is ambiguous, or lacks a required argument, yields a question mark (?). In the last case an error message is printed to the standard error.

Operation on getopt: get_optname = proc (go: getopt) returns (string)

effects Returns the name of the current option such as "-a" or "–verbose".

Operation on getopt: get_optarg = proc (go: getopt) returns (string) signals (no_argument)

effects If the current option has an argument, returns the argument. Otherwise signals no_argument.

Operation on getopt: optarg_is_empty = proc (go: getopt) returns (bool)

effects Returns true if and only if the current option does not have an argument.

Operation on getopt: optarg_is_full = proc (go: getopt) returns (bool)

effects Returns true if and only if the current option has an argument.

Operation on getopt: get_optind = proc (go: getopt) returns (int)

effects Returns the index of the next argument to be processed in the argument vector.

Operation on getopt: get_opterr = proc (go: getopt) returns (bool)

effects Returns whether an error message is printed when an option is unknown or without a required argument.

Operation on getopt: set_opterr = proc (go: getopt, opterr: bool)

modifies go.
effects If opterr is true, changes go so that an error message is printed when an option is unknown or without a required argument (this is the default behavior). Otherwise changes go so that no error messages are printed.

Operation on getopt: set_output = proc (go: getopt, output: stream)

modifies go.
effects Changes go so that error messages are printed to output.

Operation on getopt: get_non_options = proc (go: getopt) returns (sequence[string])

requires The options operation has been invoked on go and it terminated normally.
effects Returns the sequence of the non-option arguments.

Operation on getopt: non_options = iter (go: getopt) yields (string)

requires The options operation has been invoked on go and it terminated normally.
effects Yields each non-option argument in the same order as in the argument vector that is used for creating go.

5.6.3 Environment Variables

Routine: getenv = proc (name: string) returns (string) signals (not_found)

effects Returns the value of the environment variable associated with name if such a variable exists; otherwise signals not_found.

5.6.4 System Command Execution

Routine: system = proc (command: string) returns (int)

effects Invokes an implementation-defined command processor to interpret command and returns an implementation-defined value.

5.6.5 Program Termination

Routine: terminate = proc (status: int)

effects Attempts to flush all open streams with unwritten buffered data, then closes all open streams, and then terminates the current process in the condition specified by status.

5.7 Miscellaneous Abstractions

5.7.1 Unsigned Integers

Data type: uint = data type is create, to_int, add, sub, mul, div, mod, max, min, lt, le, ge, gt, and, or, xor, not, shift, parse, hex_parse, oct_parse, unparse, hex_unparse, oct_unparse, equal, similar, copy

Overview

Objects of type uint are immutable and represent nonnegative integers less than UINT_MODULO, where UINT_MODULO = 2 ** UINT_BIT and UINT_BIT is the implementation-defined constant such that UINT_MODULO > Int_Max.

Operations

Operation on uint: create = proc (i: int) returns (uint) signals (negative_argument)

effects Signals negative_argument if i < 0; otherwise returns the unsigned integer that has the same value as i.

Operation on uint: to_int = proc (u: uint) returns (int) signals (overflow)

effects Signals overflow if u can not be represented as an int object; otherwise returns the integer that has the same value as u.

Operation on uint: add = proc (u1, u2: uint) returns (u3: uint)

effects u3 is congruent to (u1 + u2) (modulo UINT_MODULO).

Operation on uint: sub = proc (u1, u2: uint) returns (u3: uint)

effects u3 is congruent to (u1 - u2) (modulo UINT_MODULO).

Operation on uint: mul = proc (u1, u2: uint) returns (u3: uint)

effects u3 is congruent to (u1 * u2) (modulo UINT_MODULO).

Operation on uint: div = proc (u1, u2: uint) returns (u3: uint) signals (zero_divide)

effects Signals zero_divide if u2 is zero; otherwise u1 is equal to (u2 * u3 + r) for some nonnegative integer r less than u2.

Operation on uint: mod = proc (u1, u2: uint) returns (u3: uint) signals (zero_divide)

effects Signals zero_divide if u2 is zero; otherwise u3 is less than u2 and u1 is equal to (u2 * q + u3) for some nonnegative integer q.

Operation on uint: max = proc (u1, u2: uint) returns (uint)

effects Returns the larger of u1 and u2.

Operation on uint: min = proc (u1, u2: uint) returns (uint)

effects Returns the smaller of u1 and u2.

Operation on uint: lt = proc (u1, u2: uint) returns (bool)

effects Returns true if and only if u1 is less than u2.

Operation on uint: le = proc (u1, u2: uint) returns (bool)

effects Returns true if and only if u1 is less than or equal to u2.

Operation on uint: ge = proc (u1, u2: uint) returns (bool)

effects Returns true if and only if u1 is greater than or equal to u2.

Operation on uint: gt = proc (u1, u2: uint) returns (bool)

effects Returns true if and only if u1 is greater than u2.

Operation on uint: and = proc (u1, u2: uint) returns (uint)

effects Returns the bitwise AND of u1 and u2.

Operation on uint: or = proc (u1, u2: uint) returns (uint)

effects Returns the bitwise inclusive OR of u1 and u2.

Operation on uint: xor = proc (u1, u2: uint) returns (uint)

effects Returns the bitwise exclusive OR of u1 and u2.

Operation on uint: not = proc (u: uint) returns (uint)

effects Returns the one’s complement of u.

Operation on uint: shift = proc (u: uint, count: int) returns (uint)

effects Returns an unsigned integer that is the result of shifting u left by count bit positions if count is positive; otherwise returns an unsigned integer that is the result of shifting u right by -count bit positions.

Operation on uint: parse = proc (s: string) returns (u: uint) signals (bad_format)

effects Signals bad_format if s contains any character other than decimal digits; otherwise u is congruent to the integer represented by s (modulo UINT_MODULO).

Operation on uint: hex_parse = proc (s: string) returns (u: uint) signals (bad_format)

effects Signals bad_format if s contains any character other than hexadecimal digits; otherwise u is congruent to x (modulo UINT_MODULO), where x is the integer represented by s in hexadecimal notation.

Operation on uint: oct_parse = proc (s: string) returns (u: uint) signals (bad_format)

effects Signals bad_format if s contains any character other than octal digits; otherwise u is congruent to x (modulo UINT_MODULO), where x is the integer represented by s in octal notation.

Operation on uint: unparse = proc (u: uint) returns (string)

effects Returns the string such that parse(unparse(u)) = u. Leading zeros are suppressed.

Operation on uint: hex_unparse = proc (u: uint) returns (string)

effects Returns the string such that hex_parse(hex_unparse(u)) = u. Leading zeros are suppressed. The letters from ‘a’ through ‘f’ are used for hexadecimal digits with values from 10 to 15, respectively.

Operation on uint: oct_unparse = proc (u: uint) returns (string)

effects Returns the string such that oct_parse(oct_unparse(u)) = u. Leading zeros are suppressed.

Operation on uint: equal = proc (u1, u2: uint) returns (bool)

effects Returns true if and only if u1 and u2 is the same unsigned integer.

Operation on uint: similar = proc (u1, u2: uint) returns (bool)

effects Equivalent to the equal operation.

Operation on uint: copy = proc (u: uint) returns (uint)

effects Simply returns u.

Appendix A How to Install CLU2C

A.1 Basic Installation

This section shows basic instructions for installing CLU2C on UNIX systems. See section MS-DOS Installation, for the instructions for installing CLU2C on MS-DOS systems. Now we assume that you have unpacked the source distribution package and are at the top source directory.

1. Type ‘./configure’ to run the configure script. This script creates a number of files including ‘config.h’ and ‘config.mk’ in the current working directory, and also creates ‘Makefile’ in every directory. See section Configurations, for more detail about the configure script.
2. Type ‘make’ to compile the entire package.
3. Type ‘make install’ to copy executable programs to ‘/usr/local/lib/clu2c/bin’, header files to ‘/usr/local/lib/clu2c/include’, object code archives and other data files to ‘/usr/local/lib/clu2c/lib’, and two shell scripts to ‘/usr/local/bin’.
4. Optionally, type ‘make distclean’ to delete all files that have been created by configuring or building the package.

A.2 Configurations

CLU2C source distribution package comes with a shell script named configure, which automatically guesses various system-dependent parameters used to compile the package. The first thing to do for installation is running this script.

After guessing system-dependent parameters, configure creates the files ‘config.h’, ‘config.mk’, ‘config.status’, ‘config.cache’, ‘config.log’, and ‘fakeclu.sh’ in the current directory, as well as the files ‘Makefile’ and ‘Makefile.top’ in every directory.

A.2.1 Options for configure

The configure script recognizes the following options to control how it operates.

‘--prefix=directory’

Set the common prefix for installation directories to directory. The prefix is set to ‘/usr/local’ unless this option is specified.

‘--srcdir=directory’

Tell the configure script where the source code for this package resides. Usually you do not have to specify this option, for the configure script automatically guesses the source directory based on how it is invoked. For example, if you invoke the configure script by typing ‘./configure’, the source directory is set to ‘.’.

‘--disable-dynamic-loading’

Forbid the garbage collector to scan data segments associated with dynamic libraries. This option is mandatory if you use rather old SunOS (3.x or 4.0.x).

‘--with-bsd-byte-operations’

Use BSD byte operations such as bcopy and bcmp, even if standard memory operations such as memcpy and memcmp are available. (On NEWS-OS 4.2R, memcpy is much slower than bcopy.)

‘--with-clu2c’

Use the installed CLU2C system to compile CLU source files. You should not specify this option unless CLU2C is already installed.

‘--with-getwd’

Use getwd to get current working directory even if getcwd is available. (On SunOS 3.x and 4.x, getcwd invokes pwd.)

‘--with-gnu-as’

Declare that you will use the GNU assembler. Currently this option has an effect on Sony CISC NEWS only.

‘--with-input-code=coding-system’

Set the default coding system for file input to coding-system. It is set to ‘autoconv’ unless this option is specified.

‘--with-output-code=coding-system’

Set the default coding system for file output to coding-system. It is set to ‘iso-2022-jp’ unless this option is specified.

The ‘--with-input-code’ and ‘--with-output-code’ options accept the following names as a specification for coding systems.

‘noconv’

No code conversion is performed. A file is treated as a byte sequence.

‘euc-japan’

Japanese EUC.

‘sjis’

Shift JIS.

‘iso-2022-jp’

ISO-2022-JP. See Japanese Character Encoding for Internet Messages (RFC 1468), for more detail about this coding system.

‘autoconv’

Guess the coding system automatically. This can be specified only as an input coding system.

A.2.2 Presetting ‘Makefile’ Variables

You can control values of some ‘Makefile’ variables via environment variables. The preset value precedes the value configure guesses. For example, if you want to use cc for the C compiler, you can achieve it by setting the CC environment variable to cc prior to running configure. If you use the Bourne shell or its descendant, you can do like the following:

CC=cc ./configure

Or, if you have the env program, you can do like the following:

env CC=cc ./configure

The following Makefile variables can be preset in such a way. Typical values that configure guesses are in square brackets.

CC

C compiler. [gcc or cc]

CFLAGS

Default options to the C compiler. [-O -g for gcc, -g for other C compilers]

AS

Assembler. [as]

LIBS

Additional libraries for linking program. [-lm]

LDFLAGS

Additional options to the C compiler for linking. [(empty)]

AR

Archive and library maintainer. [ar]

ARFLAGS

Default flags to ar. [ru]

RANLIB

Library randomizer. [ranlib or :]

A.3 MS-DOS Installation

There are two choices for installing CLU2C on MS-DOS systems. Probably most users would like to get a binary distribution package and install it, without compiling any source code. On the other hand, you may want to get a source distribution package and begin the installation process by compiling source code. In either case, you need to install DJGPP prior to the installation of CLU2C.

A.3.1 Requirements

CLU2C on MS-DOS systems requires DJGPP Version 2 (or later) to be installed. DJGPP is available via anonymous FTP from SimTel mirror sites. At the minimum, you need to get the following files.

• ‘v2/djdevXXX.zip’
• ‘v2/readme.1st’
• ‘v2gnu/bnuXXXb.zip’
• ‘v2gnu/gccXXXb.zip’
• ‘v2misc/csdpmi1b.zip’

See the file ‘v2/readme.1st’ for more detail about DJGPP.

A.3.2 Installing from Binary Distribution Package

This subsection shows instructions for installing CLU2C on MS-DOS systems from a binary distribution package.

1. Make sure that you have installed DJGPP Version 2.00 (or later) and gcc works fine.
2. Create an installation directory for CLU2C. The default is ‘c:\clu2c’, although you can choose any other directory. For example, if you choose the default, do like:

   mkdir c:\clu2c
   

3. Go to the installation directory you have chosen, like this:

   c:
   cd \clu2c
   

4. Unpack the binary distribution package in that directory. For example,

   lha x somewhere\clu200b.lzh
   

   or

   unzip somewhere\clu200b.zip
   

5. If you have chosen a directory other than ‘c:\clu2c’ as an installation directory, you need to set the CLU2CROOT environment variable to point to the installation directory. For example, if you have chosen ‘c:\local\clu2c’ as an installation directory, put the line

   set CLU2CROOT=c:\local\clu2c
   

   into your ‘autoexec.bat’.

6. Add the ‘bin’ subdirectory of the installation directory (‘c:\clu2c\bin’ for example) to the command search path. For example, put the line

   set PATH=c:\clu2c\bin;%PATH%
   

   into your ‘autoexec.bat’.

A.3.3 Installing from Source Distribution Package

This subsection shows instructions for installing CLU2C on MS-DOS systems from a source distribution package. We assume that you have unpacked the source distribution package and are at the top source directory.

1. Make sure that you have installed DJGPP Version 2.00 (or later) and gcc, ar, and ranlib work fine.
2. Make sure that the make program you will use to build CLU2C is invoked by simply saying ‘make’.
3. Type ‘configure’ to run the batch file ‘configure.bat’. This batch file creates a number of files including ‘config.h’ and ‘config.mk’ in the current working directory, and also creates ‘Makefile’ in every directory. Unlike the configure script for UNIX systems, however, ‘configure.bat’ does not guess system-dependent parameters. Instead, it merely copies configuration files from the ‘config’ directory.
4. Look into ‘config.h’ and ‘config.mk’. You may have to modify these files manually. Whenever you modify ‘config.h’, you must recompile all the C files that include this header file. Whenever you modify ‘config.mk’, you must re-create makefiles by typing ‘make mkfiles’.
5. Type ‘make’ to compile the entire package.
6. Type ‘make install’ to copy a number of files to the installation directory. By default, executable programs are copied to ‘c:\clu2c\bin’; header files are copied to ‘c:\clu2c\include’; and object code archives and other data files are copied to ‘c:\clu2c\lib’. If nothing seems to happen, rename the file ‘INSTALL’ as another name, say ‘INSTALL.doc’, and try again.
7. Set the CLU2CROOT environment variable (if necessary) and the command search path, as in installing from binary distribution package.
8. Optionally, type ‘make distclean’ to delete all files that have been created by configuring or building the package.

We have found the difficulty of writing general makefiles for MS-DOS systems. In your environment, things might not go well as described above. We expect some effort on your side.

A.4 Compiling in a Separate Directory

This section shows instructions to compile CLU2C in a separate directory.

1. Make sure the make program you use has a VPATH feature.
2. Go to the top source directory.
3. Run the configure script in the source directory if you have not run.
4. Make sure that the source directory does not contain any object files. Type ‘make mostlyclean’ if you have no confidence.
5. Type ‘make cfiles’ to prepare all the C files that are to be generated from CLU files.
6. Prepare a directory where you wish to compile the package and go to that directory.
7. Run the configure script.

Now you can compile in the build directory. Type ‘make’ to compile the entire package; Type ‘make install’ to install the resulting products.

For example, if you have unpacked the distribution package into ‘/usr/local/src/clu2c-2.0’ and want to do compilation in the ‘/usr/local/src/clu2c-2.0/build’, command lines you type might look like this:

cd /usr/local/src/clu2c-2.0
./configure
make mostlyclean cfiles
mkdir build
cd build
../configure
make

A.5 Common Targets

Here is the list of common targets that are defined in ‘Makefile’ in almost every directory. These targets are applied to the current directory and all its subdirectories recursively.

‘all’

Compile the entire source files. This is the default target.

‘install’

Compile the entire source files and copy the resulting products to the file names where they should reside for actual use.

‘clean’

Remove all the files that are created by running make.

‘mostlyclean’

Remove almost all the files that are created by running make but do not remove C files that are translated directly or indirectly from CLU source files.

‘distclean’

Remove all the files that are created by running configure and make. If you did not create any other files, ‘make distclean’ restore the source tree to its original contents.

‘mkfiles’

Recreate ‘Makefile’. You have to make this target whenever you modify the file ‘config.mk’ manually.

‘cfiles’

Prepare C source files that are translated directly or indirectly from CLU source files. Some make programs fail to follow the chain of suffix rules. Particularly, they understand that ‘foo.o’ is to be made from ‘foo.c’ but cannot think of this C source file being made from ‘foo.clu’. In this case, you have to ‘make cfiles’ first before you ‘make all’.

A.6 Makefile Structure

Every ‘Makefile’ is actually a concatenation of three files:

‘Makefile.top’

This file resides in each directory, and contains variable definitions that may vary dependent on how the configure script is invoked and are specific to each directory. VPATH, srcdir, and top_srcdir are defined here. This file is created automatically by running the configure script.

‘config.mk’

This file resides in the top build directory, and contains variable definitions that may vary dependent on how the configure script is invoked and can be shared by all the ‘Makefile’. This file is created automatically by running the configure script.

‘Makefile.unix’

‘Makefile.dos’

One of these files constitute the rest of ‘Makefile’. These files reside in each directory, and contains variable and rule definitions that are specific to each directory and should not be modified. These files are included in the source distribution package.

In every directory there is a file named ‘Makefile.in’. This file is processed by the m4 macro processor to generate ‘Makefile.unix’ and ‘Makefile.dos’. Note that these files are included in the distribution package and you do not have to prepare the m4 macro processor in order to compile CLU2C.

A.7 Getting CLU2C

The source and binary distribution packages of the latest version of CLU2C is available via anonymous FTP from the host ftp.is.titech.ac.jp at the directory ‘pub/clu2c’. The following files are placed at that directory.

‘clu2c-version.tar.gz’

Source distribution packages for UNIX systems. These are gzipped tar files.

‘cluvers.lzh’

‘cluvers.zip’

Source distribution packages for MS-DOS systems. These are archive files archived by lha or zip.

‘cluverb.lzh’

‘cluverb.zip’

Binary distribution packages for MS-DOS systems. These are archive files archived by lha or zip.

Appendix B Copying CLU2C

The following are the terms and conditions for copying, modifying, and distributing CLU2C.

1. Part of this software derived from PCLU is subject to the same terms and conditions as those applied to PCLU, whether the source code has been modified or not.
2. Part of this software derived from the conservative garbage collector is subject to the same terms and conditions as those applied to the conservative garbage collector, whether the source code has been modified or not.
3. Permission is granted to use, copy, modify, and distribute part of this software derived from neither PCLU nor the conservative garbage collector, provided that all copyright notices are preserved on all copies and that a verbatim copy of these terms and conditions are included in all copies.
4. THIS SOFTWARE IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESS OR IMPLIED. ANY USE IS AT YOUR OWN RISK.

Index

Footnotes

(1)

On MS-DOS systems, the clulink program further creates ‘a.exe’ from ‘a.out’.

Table of Contents

About This Document

This document was generated on September 9, 2012 using texi2html 5.0.

The buttons in the navigation panels have the following meaning:

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

• 1. Section One
  • 1.1 Subsection One-One
    • ...
  • 1.2 Subsection One-Two
    • 1.2.1 Subsubsection One-Two-One
    • 1.2.2 Subsubsection One-Two-Two
    • 1.2.3 Subsubsection One-Two-Three     <== Current Position
    • 1.2.4 Subsubsection One-Two-Four
  • 1.3 Subsection One-Three
    • ...
  • 1.4 Subsection One-Four

This document was generated on September 9, 2012 using texi2html 5.0.