GENMAKE(1)

NAME
genmake - generate make or shape files for Opal programs

SYNOPSIS
genmake [ options ... ]
( top-level-structure [ top-level-command ]
| -S system structure ... )

DESCRIPTION

genmake generates description files for make(1) or shape(1) to maintain OPAL programs and librarys. This files support the compilation, linkage, and - if shape(1) is involved - version management of small to large software systems based on the OPAL compilation system ocs(1).

CONCEPTS

An Opal program consist of a top-level structure and the structures that are transiently imported by it. The top-level structure must export (at least) one special constant, the top-levelcommand, which defines the interaction of the program with its environment.

The structures of an OPAL program reside in systems. The system which holds the top-level structure is called the top-level system. Systems may be based on subsystems which provide librarys of OPAL structures. The based-on relation of systems is always acyclic.

A system may be frozen, in which case it is not considered for recompilation checks, or it may be evolving, in which case it is.

Under UNIX, each system is exclusively located within a directory of the filesystem, the name of which coincides with the systems name. The system directory contains files for the signature, implementation, signature property, and implementation property parts of an Opal structure. The intermediate compilation products derived from this files are either located in a directory named OCS, or populate the system directory itself. If the shape toolkit is used, the system directory and the OCS subdirectory both contain an ./AtFS subdirectory, propably linked to the central project repository.

OPERATION

genmake is invoked in the directory of the system a maintenance file shall be generated for. If top-level-structure is given, genmake generates a maintenance file for the top-level system of an OPAL program. If top-level-command is ommitted, the name of the the top-level structure is used instead. If -S system is given, genmake generates a maintenance file for a subsystem. Then structure ... specifies the names of the structures incorporated into the subsystem.

For each of the parts of the top-level structure (or the structures of a subystem), the systems where the imported structures reside are looked up. Is this the current system, the process is recursively continued on the retrieved structure.

CONTROL OPTIONS

The following options directly control the operation of genmake.

-s[mode] dir/system
    Incorporate system located in dir/system as subsystem into the current system. Note that for top-level systems, all subsystems belonging to the program must be specified with -s. When genmake retrieves the location of imported structures, it first searches the current system, and then all subsystems specified by the option in order they appear on the command line. -s without mode is equivalent to -sdh. mode controls the type of subsystem and is a combination of:

    f   The subsystem is frozen. Structures belonging to it are not considered for recompilation checks. genmake asserts a structure is provided by a frozen subsystem if its derived signature export file is present.

    d   The subsystem is evolving, i.e. still under development. Structures belonging to it are considered for recompilation checks. genmake asserts a structure is provided by an evolving subsystem if its signature file is present.

    h   The derived objects of the system reside in hidden subdirectorys.

    e   The derived objects populate the system directory.

-shape
    Generate a description file for shape. The default is to generate a file for make.

-gen filename
    Name the generated description file filename. The default name is Shapefile if in shape mode, and Makefile if in make mode.

-defs filename
    Take default macro definitions included in the generated description file from filename. The hardwired default is $(OCS)/etc/Makedefs in make mode, and $(OCS)/etc/Shapedefs in shape mode.

-rules filename
    Take default target and rules from filename.top for top-level systems, and filename.sub for subsystems, respectively. The hardwired default is $(OCS)/etc/makerules in make mode, and $(OCS)/etc/shaperules in shape mode.

-rms
    Generate descriptions files for the shape_OCS(1) extension of the shape revision management system shape_RMS(1).

-R  Recursivly generate description files for all incorporated evolving subsystems. The specification of the structures belonging to each subsystems is derived from the dependency closure induced by the structures of the current system.

-V  Run genmake in verbose mode.

OC OPTIONS

The following options are passed to the OPAL compiler oc(1).

-v[level][:struct]
    Verbose processing. The default is -v0, -v with the level omitted is equivalent to -v1. If struct is specified, the option only applies to it, and all global oc options for this structure are cancelled. level is one of:

    0   Quiet compilation.

    1   Display the compilation phases.

    2   Display the compilation phases and their sub-phases.

    3   Display even small compilation steps.

-w[level][:struct]
    Display warnings. The default is -w1, -w with the level omitted is equivalent to -w2. If struct is specified, the option only applies to it, and all global oc options for this structure are cancelled. level is one of:

    0   Do not generate warnings. Only errors are displayed.

    1   Display warnings for unusual use of programming constructs, e.g., a duplicate pattern.

    2   Like -w1, but additionally display hints for possible programming errors, e.g., missing patterns.

-o[kind][:struct]
    Optimize code. The default is no optimization, -o with the kind omitted is equivalent to -o1. If struct is specified, the option only applies to it, and all global oc options for this structure are cancelled. kind is a combination of:

    1   This is an alias for the combination eucmC.

    2   This is an alias for the combination 1pgT.

    e   Perform common subexpression elimination.

    u   Perform unfolding of function definitions and of local equations. This option allows the Opal compiler to code functions and equations in a none-strict. fashion. The resulting program is only robustly correct, i.e. satisfies the semantics only for terminating programs.

    c   Perform optimization of constant expressions. The resulting program evaluates each detectable constant expression not more then once. Note that the memory allocated by the object resulting from this evaluation can never be retrieved.

    m   Perform optimization of memory allocation and garbage collection. The resulting program performs "on-the-fly" reusage of memory cells and selective update of single threaded data objects.

    p   This option allows the Opal compiler to treat runtime errors as a "no-case", which allows some subtle optimizations. It results only robust correct code, which might core dump.

    g   This option enables the use of the optimization export files for inter-structure optimizations. Function definitions and properties are made available accross structures boundarys. The use of this option enforces recompilation dependencies between structure implementations.

    T   This option generally allows the Opal compiler to perform some optimizations which might be expensive by means of compilation time.

    S   This option generally allows the Opal compiler to perform optimizations which might be speculative by means of code size (but not of code speed).

    C   The C compiler should perform optimizations as well.

-d[kind][:struct]
    Controls generation of code for debugging. The default is to generate code only for the runtime check of detectable partialities, -d with the kind omitted is equivalent to -dc. If struct is specified, the option only applies to it, and all global oc options for this structure are cancelled. kind is a combination of:

    T   Generate code for tracing all function entries and exits. Dependent on the optimization level, not all function calls are considered.

    t   Generate code for tracing all entries and exits of exported functions. Dependent on the optimization level, auxiliary functions my become implicitely exported.

    d   Generate information for use of an object code debugger.

-oc1:struct string
    Directly pass string to the frontend of oc when compiling struct. All global options are cancelled for the structure.

-oc2:struct string
    Directly pass string to the backend of oc when compiling struct. All global options are cancelled for the structure.

-cc:struct string
    Directly pass string to the C compiler oc when compiling struct.

-cinter:struct
    Instruct oc to generate a C interface header for structure struct which declares symbolic names for the exported functions. Note that the C header will be found in the systems hidden directory if the system is hidden.

-ctmpl:struct
    Instruct oc to generate C templates for structure struct, which may be used to derive a handcoded implementation. This also affects the kind of derivation rule generated for this structure. The templates will be found in the systems hidden directory if the system is hidden.

ENVIRONMENT

OCS The place where the Opal Compilation System resides.

FILES

SEE ALSO
oc(1), shape_ORS(1)

P. Pepper (ed.), The Programming Language Opal, Technical University of Berlin, FB 20, Report 91-10, 1991

DIAGNOSTICS

Cannot locate structurestruct
    genmake could not locate struct in the current system or any of the subsystems supplied with the option -s.

Cycle in import Relation. Members are:structs
    genmake has detected a cyclic import relation, which is not allowed in OPAL.

BUGS

The whole program is DRAFT!

Rulefiles for other operation then with shape_OCS(1) currently do not exist.

Diagnostics for fail of structure lookup should be more instructive.

The need to speciy all subsystems a top-level system is based on, even indirectly, violates the principle of transparency.

This man page is not complete.

Property parts of structures are currently not supported.

AUTHOR

wg@cs.tu-berlin.de