NAME

gluepack - Process Basis package files.


SYNOPSIS

gluepack [<options>] [[-i] <filelist>] [-o <outputfilename>]


DESCRIPTION

gluepack processes Basis package configuration files. It reads input from the list of files in the order specified on the command line, or stdin if there are none. From this input, gluepack produces an output file whose name defaults to pack.m if no -o option is specified. This output file must be processed by mppl(1) into standard Fortran. It consists of routines which at runtime add information about the packages declared in the input to the basis(1) database, call appropriate initializers and other specific routines for the packages, and supply the ``glue'' which allows users to interface with builtin functions and with the data and functions of foreign packages.

If you use mio(1), mio runs config for you. You should have a package configuration file (ending with a suffix ``.pack'') for each package that has configuration requirements covered by config.


OPTIONS

The options to config may be specified in any order on the command line. The order is not significant, except that the input files will be read in the order specified.

-cdriver
Write the glue in C instead of Fortran. The output file defaults to pack.c unless the -o option is specified.

-d[t]
Echo each input token read to stderr. Print out what type of token gluepack thinks it is, if the optional t is present. This is really a debugging option used by developers, and would be of little use to ordinary users.

-e
Echo input to stderr. Again, useful mainly to developers.

-I dir
Add the directory dir to the list of directories to be searched for input files.

-o outputfile
Write the output to file outputfile. If not specified, the output will go to a file called 'pack.m.' Error diagnostics and debugging output, however, always go to stderr.


GLUEPACK INPUT

Gluepack input file(s) consist of specifications for one or more packages. These specifications consist of one or more statements, separated by commas or white space. Generally gluepack input is pretty free form; statements may be continued from line to line, and they may be separated by either commas or white space. Just about the only restriction is that a statement may not begin in one file and end in another. Except as separators, commas and white space are ignored. Comments, which begin with an octothorpe '#' and extend to the end of the line, are also ignored, and may occur anywhere, even in the middle of a statement.

Each package specification starts with one of the reserved words package or foreign. Statements occurring in the input prior to one of these reserved words will apply to package 'par', which is always present. Within each package specification there are one or more config statements. The form and explanation of each type of statement is as follows:

  pkgname = string

This is the only statement which is required to be present in a specification. pkgname is an identifier consisting of three or fewer alphanumeric characters, starting with a letter. string is a singly or doubly quoted string which contains a short description of the package. For example:

  rfe = "Finite-Element Radiation"

There can only be one such statement in a package specification.

macfile = filename
macfile = filenamelist
Here filename is the name of a file consisting of Basis code that is to be read in at initialization time; filenamelist is a list of such file names, enclosed in parentheses or square brackets. The list may be delimited by commas or white space. macfiles are read in the order specified in the list but after any files specified in a startups list; see below. The following directories are searched, in the order given, for the specified file or files (names in capital letters are environment variables presumably set by the user's .cshrc or .cshrc.ext files): first, in order, any path names specified in paths statements, described below; next, in reverse order, any path names specified in codefile statements, also described below; and finally, the directory out of which Basis was executed, $WRK, $HOME, and finally $BASIS_ROOT/include, There may be more than one macfile statement in the input. The macfile reserved word is going to go away in some future version of Basis, to be replaced by the startups reserved word described next. Examples of macfile usage:
  macfile=lasnex_functions
  macfile=(init1 init2)

startups = filename
startups = filenamelist
Here filename is the name of a file consisting of Basis code that is to be read in at initialization time; filenamelist is a list of such file names, enclosed in parentheses or square brackets. The list may be delimited by commas or white space. startups are read in the reverse of the order specified on the list, prior to any macfiles. The directory search order is as described above. The startups statement will someday replace the macfile statement.

codefile = dirname
codefile = dirnamelist
dirname is the name of a directory, and dirnamelist is a comma- or white space-delimited list of directories enclosed in parentheses or square brackets. This statement may be used to specify additional directories to be searched for macfiles, comment files, or files intended to be listed by the Basis command more. There may be more than one codefile statement in the input. The directories will be searched in the reverse order of their specification in codefile statements, before the default directory list described above, but after any directories specified in the paths statement described next. The codefile statement is eventually going to go away and be replaced by the paths statement. Example:
  codefile = (/usr/local/lasnex/include
              /usr/local/lasnex/users)

paths = dirname
paths = dirnamelist
dirname is the name of a directory, and dirnamelist is a comma- or white space-delimited list of directories enclosed in parentheses or square brackets. This is similar to the codefile statement except that directories on this list will be searched in the order specified, prior to any codefile directories or default directories. This statement will eventually replace the codefile statement.

firstpkg = pkgname
firstpkg = pkgnamelist
pkgname is a package name as above, pkgnamelist is a list of package names delimited by commas or white space and enclosed in parentheses or square brackets. This statement is used to specify the initial search stack, with the highest element on the stack on the left. ('par' is always by default on top of the stack.) When Basis is searching for a variable or function, it searches the packages in order starting at the stack top. Packages are initialized and fired up as they are placed on the stack. A package will be dormant, and you will be unable to access its variables, if it is not named in a firstpkg statement. There may be more than one firstpkg statement in the input. Example:
  firstpkg=(att hyt imc)

iotable = unsigned integer
iotable = list of unsigned integers
The list, as usual, is enclosed in square brackets or parentheses and may be comma- or white space-delimited. This allows you to reserve one or more FORTRAN I/O unit numbers so that the rest of Basis will not use them. There may be more than one iotable statement in the input. Example:
  iotable=(50,51,52,53,54)

routine [ = name ]
In this statement routine is one of the reserved words init, vers, gen, genp, exe, exep, fin, or finp. The presence of one or more of these words in a package specification means that you are supplying a FORTRAN integer function or functions; you may specify the name of the function in the optional assignment, and if you do not, its name will default to pkginit, pkgvers, etc., where pkg is the name of the particular package. Example (this example shows the use of both white space and commas as separators):
  gen exe , fin = alldone

means that you are supplying functions named pkggen, pkgexe, and alldone (in lieu of pkgfin).

variable = string
The variable in this statement is one of the reserved words discussed below. Usually string is a singly or double quoted string, but not always. Although there may be more than one assignment to the same variable, only the last one will be effective. The reserved words are as follows:

cprompt
Allows you to specify the Basis runtime prompt. The default is 'Basis >'. Example:
  cprompt='HPLas> '

codename
Allows you to specify a codename, which may not be longer than eight characters. The default is ``Basis''. Example:
  codename='Lasnex'

verbose
Specifies the initial value of the Basis variable verbose, which if set, causes a lot of messages to be sent to the terminal and log file. verbose may be set to only two values, yes and no (no quotes). It defaults to yes. Example:
  verbose=no

echo
Specifies the initial value of the Basis variable echo, which if set, causes the contents of any macfile or other basis code file, to echo to the terminal when it is read. Like verbose, this variable may only be set to yes or no. It defaults to yes. Example:
  echo=no

SYSTEM CPUlist
This is the reserved word SYSTEM (which must begin in column 1) followed by a list of one or more CPU specifiers separated by white space or commas (no parentheses). Currently, the allowed CPU specifiers are CS2, SOL, SUN4, HP700, RS6000, SGI, GENERIC, XMP, YMP, C90, CRAY2, ULTRIX, VAX, MAC, and MIPS. These specifiers control the setting of toggles in config, which initially are all toggled on. The effect of a CPUlist is to turn off all toggles except those for CPU's contained in the list, which will be turned on. Then any statements following the CPUlist will only be processed by config if config is processing for one of the CPU's in the list. config is normally processing for the CPU on which it is executing, but it can be set for a different CPU by the -CPU option described earlier. The main use of this statement (and the following) is to specify the names of libraries, library paths, codefiles, etc., which may differ from one platform to another. Example:
  SYSTEM HP700
  codename=hp700
  SYSTEM SOL
  codename=sol
  SYSTEM SUN4
  codename=sun4

SYSTEM +CPU or -CPU
Here, CPU is one of the allowed CPU specifiers enumerated above. The effect of +CPU is to turn on the toggle for just that one CPU, and of -CPU is to turn it off. No other toggles are affected. Examples:
  SYSTEM +YMP
  SYSTEM -SOL


EXAMPLES

config par.pack ezn.pack

Processes input files par.pack and ezn.pack and puts the output in pack.m.


SEE ALSO

mppl(1), basis(1), mio(1)