22. Utility Programs

Several utility programs are provided with the front end. Most of the utility programs help with various link-time issues and are meant to be called from a driver program or script. One (mk_errinfo) is a tool program used when modifying the front end. The source for these programs is in the util directory of the release structure.

22.1. edg_prelink

edg_prelink.c contains the “prelinker” program. edg_prelink.h contains related declarations. The prelinker is invoked at link time to manage automatic instantiation of template entities. It is given a complete list of the object files and libraries that are to be linked together. It examines the external names defined and referenced within those files, and finds cases where template entities are referenced but not defined. It then examines information in the object files that describes instantiations that could have been done during compilation, and assigns the needed instantiations to appropriate files. edg_prelink then invokes the compiler again to compile those files, which will do the necessary instantiations.

The prelinker uses UNIX commands like nm to extract information about object files, so it may need adaptation to run in other environments.

The invocation of the prelinker looks like

edg_prelink [ options ] files

where the files list includes all object files and libraries, and the options are:

-a n	Specify whether a definition list file should be created. A definition list file is created if n is nonzero. The default is specified by the PL_DEFAULT_USE_DEFINITION_LIST_FILE configuration flag.
-b	List object files mode. This mode is used when the driver needs to get a list of object files including any instantiation object files created in one instantiation perobject mode. The prelinker simply creates an object file list that is written to the file specified by the -o option.
-c command	Specify the version of the nm command to be used.
-D	Do not assign instantiation to nonlocal object files. Instantiations may only be assigned to object files in the current directory.
-f fmt	Specify the nm format to be used. fmt is one of solaris, SGI, SVR4, HPUX, gnu, CLIX, MacOSX, orMacOSX64.
-i	Ignore nm output lines that are not formatted properly.
-L directory	Specify a library directory to be searched for libraries.
-m	Do not demangle identifier names that are displayed.
-n	Update the instantiation list but don’t recompile the files.
-N	If a file from a nonlocal directory needs to be recompiled, do the compilation in the current directory. An updated list of object files and library names is written to the file specified by the -o option so that the driver program can tell that alternate versions of some of the object files should be used.
-o file-name	Write an updated list of object files and library names is written to the file specified by file-name. This option must be specified when the -N or -O option is used.
-O	One instantiation per object mode is being used. A list of object files, including the instantiation object files associated with the object files specified on the prelinker command line, is written to the file specified by the -o option.
-q	Turns off verbose mode.
-r	Don’t stop after a certain number of iterations. (The instantiation process is iterative: a recompilation may bring up new template entities that need to be instantiated, which requires another recompilation, etc. Some recursive templates can cause iteration that never terminates, because each iteration introduces another new entity that wasn’t previously there. By default, this process is stopped after a certain number of iterations.)
-R number	Override the number of reserved instantiation information file lines to be used.
-s number	Specifies whether the prelinker should check for entities that are referenced as both explicit specializations and generated instantiations. If number is zero the check is disabled, otherwise the check is enabled.
-S	Suppress instantiation flags in the object files. This causes the prelinker to recompile all of the local object files with the --suppress_instantiation_flags option.
-u	Specify whether external names have an added leading underscore. The command-line option selects the opposite of the configuration flag TARG_EXTERNAL_NAMES_GET_UNDERSCORE_ADDED.
-v	Verbose mode.
-dn	Set the debug level to n.

The files list may also have the following options intermixed with the file names:

-lxxx	Specify a library (e.g., -lstd).
-Blinkage	Specify the kind of linking to be done (e.g., static or dynamic). The linkage kind is not checked for validity.
--	Marks the end of the list of file names that is passed back to the driver when the -N option is used.

22.2. edg_munch

edg_munch is the EDG version of the USL munch utility. Its source code is in edg_munch.c, with associated declarations in edg_munch.h. edg_munch implements a lowest-common-denominator method for getting global initialization and termination code executed on systems that have no special support for that. [1]

edg_munch operates by reading as input a file that is the output of nm run on a linked executable program. It looks for names beginning with __sti__ or __std__, those being, respectively, initialization and termination routines to be called at runtime. It generates a C program that defines a data structure containing a list of pointers to the initialization and termination routines. This generated program is then compiled and linked in with the executable. The data structure is consulted at runtime by startup code invoked from _main, and the routines on the list are invoked at the appropriate times.

edg_munch takes only a single option: -u, if used, specifies whether external names have an added leading underscore. The command-line option selects the opposite of the configuration flag TARG_EXTERNAL_NAMES_GET_UNDERSCORE_ADDED.

22.3. edg_decode

edg_decode is a name demangler. The demangling code is in decode.c, with associated declarations in decode.h. A main program that uses the demangling code is provided in edg_decode.c.

edg_decode reads input from stdin and writes output to stdout. Things that look like mangled names in the input are demangled. Everything else is passed through unchanged. This makes the program suitable, for example, as a filter for the output of a linker: error messages in general are passed through unaltered, but mangled names are demangled. For example, using the cfront-like ABI,

ld: Undefined symbol
   _f__Fif

is turned into

ld: Undefined symbol
   f(int, float)

Mangled names that are ill-formed in some way are also passed through unchanged.

edg_decode usually has only a single option: -u, if used, specifies whether external names have an added leading underscore. The command-line option selects the opposite of the configuration flag TARG_EXTERNAL_NAMES_GET_UNDERSCORE_ADDED. When the IA-64 ABI is used, however, there is also a -g option, which selects the opposite of the configuration flag DEFAULT_EMULATE_GNU_ABI_BUGS, which when TRUE extends the demangling to cover some invalid mangled names put out by g++ 3.2 (and the EDG front end, when configured to emulate those bugs).

The demangling is intended to work only on names of external entities. There is some name mangling done for internal entities, or by the C-generating back end, that this program does not try to decode.

In the cfront-like ABI, names that contain double underscores in the source code will probably not be demangled correctly. This is an unfortunate consequence of using a mangling scheme that is based on the one used by cfront. The standard forbids use of double underscores in names in user code, reserving such names for the implementation, so the effect of this shortcoming is limited. Implementors should try to avoid using such names for entities with external linkage. Double underscores at the beginnings of external names do, however, work correctly. In the IA-64 ABI, a similar problem applies to names that begin with “_Z”.

The name demangling is also available through a callable interface, which is used in edg_prelink. See routine decode_identifier.

22.4. mk_errinfo

mk_errinfo translates a text file containing error message codes and associated descriptions into a pair of header files that represent this information in a manner more readily used by the front end.

The invocation of the mk_errinfo is typically

mk_errinfo error_msg.txt error_tag.txt err_codes.h err_data.h

The error_msg.txt file defines the diagnostic messages generated by the front end. This file, along with error_tag.txt, is processed by mk_errinfo to generate the err_codes.h and err_data.h include files. mk_errinfo may also be used to automatically generate the file used to generate the Error Messages appendix of this manual.

When used to generate a documentation file, the invocation is typically one of the following:

mk_errinfo -d error_msg.txt error_tag.txt generated.tex

mk_errinfo -mml error_msg.txt error_tag.txt generated.mml

mk_errinfo -rst error_msg.txt error_tag.txt generated.rst

generated.tex is the name of the generated output file containing the documentation in LaTeX format. generated.mml is the name of the generated output file containing the documentation in MML (Maker Markup Language), which can be used to create a FrameMaker document. generated.rst is the name of the generated output file containing the documentation in reStructuredText format, which can be used with Sphinx and various other tools.

error_msg.txt contains lines that have the following form:

error_code;tag;"text"

The error code is the enumeration element name that is used by the front end. The file must be specified in enumeration order. To preserve the numbering of error codes, errors may not be inserted in the middle of the file, nor may lines be removed. If an error message is no longer in use, the line on which it is defined should be prefixed with the string REMOVED. This will retain its sequence number but eliminate it from the generated tables.

The tag is an alias for a given error code to be used by the end-user to name that error in the command-line options that change the severities of diagnostics. If no tag is specified, the error code (with the ec_ removed) is used as the tag.

Some messages are used as part of the formatting of other messages (for example, the messages used to provide error context information). These messages should have a tag of INTERNAL. This prevents the message from being entered in the tag table and also prevents the message from appearing in the automatically generated documentation file.

The text string contains a quoted string similar to one that would be used in a C program to define the equivalent string. Any quote characters within the text string must be escaped.

The text string includes markers indicating the location of fill-ins in the message (e.g., %t for a type). Full information on those fill-in codes can be found in Error Reporting.

The message text may include supplementary information that is only used to improve the automatically generated documentation file (which is formatted into the Error Messages appendix of this manual). For example, an error text string might look like this

"a message with %s\='fill-in' included"

The string \='fill-in' is used when creating the documentation file as the value to be substituted for the %s. This string is removed from the error text information when the err_data.h file is created.

error_tag.txt is used to supply additional tags that may be used as aliases for diagnostic messages. This mechanism is intended to be used by customers who are packaging the front end as part of their product and allows them to assign their own set of error tags without the need to modify the distributed error_msg.txt file. Note that these tags are used in addition to (not in place of) the default tags specified in the error_msg.txt file.

Each line should be formatted as:

error_code;tag

The error code is the enumeration element name used by the front end. The tag is the alias being assigned. There may be more than one alias that references a given enumerator.

In both error_msg.txt and error_tag.txt, blank lines are ignored and lines that begin with a “#” are treated as comments.

[1]

The patch approach, by comparison, is more machine-dependent and more efficient, but still doesn’t require special linker support. The code generated by the EDG front end will work with USL’s patch, but EDG does not provide its own version of patch.