% % IMGDEF User's Guide % \input{xpsdoc_template:xpsfmt.tex} % Latex input file defining standard format \newcommand{\ourtitle}{ IMGDEF User's Guide} % title for top of page \newcommand{\modname} { imgdef.tex } % module name in library \newcommand{\modlibe} { osbdoc\_ss } % CMS library \newcommand{\version} { Version 1.0 } \renewcommand{\date} { May 11, 1988 } \thispagestyle{empty} % No header or number on first page \markright{ \ourtitle \hspace{0.5in} \date } \begin{document} % Title page \vspace*{1in} \begin{center} \begin{bf} {\LARGE User's Guide} \\ \medskip {\LARGE Image Definition Facility} \footnote{This is module \modname{} in CMS library \modlibe{}, printed \today.} \\ \bigskip \date \\ \version \\ \bigskip \end{bf} \vspace*{2.0in} {\bf Abstract } \\ \bigskip \end{center} The Image Definition Facility (IMGDEF) has been developed to improve the building of programs within SOGS and possibly other OSB systems. MMS and options files are automatically generated by IMGDEF from an image definition file, a single file which describes how to build a given program. This guide describes the IMGDEF tool, its ``language'', and how it will be used in SOGS. As part of SPR 13180, from which IMGDEF evolved, some changes were made to the SOGS build procedures, especially in the SH area. These changes are also described here. \clearpage \tableofcontents \clearpage \section{Introduction} The Image Definition Facility has grown out of System Special Project 8.5 and SPR 13180. The goal of Project 8.5 was to develop tools to aid in the building and control of OSB software. SPR 13180 was aimed specifically at removing the explicit references to low-level, shared software (SH) in SOGS by subsystem programs. It was apparent that future Support Software projects and SPR work would require many changes to the original build procedures, and that it was desireable to shield the subsystems from such modifications. The use of IMGDEF and related build conventions will help to simplify the build procedures and their maintenance. It will provide the flexibility needed for dealing with future changes in our software and VMS. \section{Usage} An image definition file contains the information on how to build an executable image. It is the primary input to IMGDEF, which then produces an options file, an MMS file to describe the LINK process, and an MMS file for building the image and its components. IMGDEF is a program in SOGSTOOLS and is run from DCL, as follows: \begin{verbatim} $ IMGDEF [/NOLINK] [/NOBUILD] imgdef-file-spec[.IMGDEF] subsystem where: imgdef-file-spec image definition file specification (can contain VMS wildcard characters) subsystem SS, PODPS, OSS, SPSS, SIM, IMTOOL, etc. /NOBUILD don't make a build MMS file /NOLINK don't make a link MMS file (implies /NOBUILD) \end{verbatim} The subsystem parameter is used to determine where the output files will go. For example, \begin{verbatim} $ IMGDEF name.IMGDEF subsystem \end{verbatim} will produce as output: \begin{verbatim} subsystem_SOURCE:name.OPT subsystem_MMS_BUILD:name_LNK.MMS subsystem_MMS_BUILD:name_BLD.MMS \end{verbatim} Typically, at least in SOGS, these logical names will be {\it stretched} from a local area to the baseline directories. Actually, the subsystem command line parameter is optional, in which case the output files will be put in the default directory. Without a known subsystem, however, some of these output files may not be completely correct, but it can serve as a quick test of the IMGDEF file. \section{IMDEF Language} The format of an IMGDEF file is that of an extended VMS options file. In addition to the normal directives and syntax of an options file, IMGDEF supports the following constructs: \begin{description}{} \item[\bf \#REQUIRE \{ BEFORE $\mid$ AFTER \} {\em options\_file\_name} ] \hfill \\ Specifies an options file that is to be listed before or after the image-specific options file on the LINK command line. Options files will appear on the LINK statement in the order in which they are given in the IMGDEF file. % \item[\bf \#INCLUDE {\em IMGDEF\_file\_name}] \hfill \\ Defines an alternate IMGDEF file from which to take input. Once the end-of-file of the included IMGDEF file is reached, lines will be taken from the original file. Included files can contain {\bf \#INCLUDE} constructs. The IMGDEF processor will initially impose an include nesting limit of 3, to prevent run-away. % \item[\bf \#DEFINE {\em symbol\_name} \ \ {\em ``replacement\_string''}] \hfill \\ This construct is used to associate some replacement string with a symbol that may be used within the IMGDEF file. Symbols are all global, that is, a symbol defined at any level of includes will be available to any IMGDEF construct after its definition. Symbols can be redefined at any time. (Note that the ``'' are required.) % \item[\bf \#({\em symbol\_name})] \hfill \\ This construct is used to substitute the replacement string defined by a previous {\bf \#DEFINE} statement for the {\em symbol\_name}. The {\bf \#( )} can appear on any non-\# lines within an IMGDEF file. % \item[\bf \#MMS\_BEGIN \{ BUILD $\mid$ LINK \} ] \hfill \\ . . . MMS statements . . . % \item[\bf \#MMS\_END] \hfill \\ Indicates a collection of MMS statements to be included at the top of the specified MMS file (if requested). IMGDEF constructs are evaluated within these lines. A {\bf \#MMS\_END} must appear within the IMGDEF file following a {\bf \#MMS\_BEGIN} statement. If the {\bf \#MMS\_END} is missing, the processor will generate an error. % \item[\bf \#TARGET {\em Target\_file\_name}] \hfill \\ This construct is used to define the target name to appear within the LINK MMS dependency rule. This statement is optional and the file name of the IMGDEF concatenated with ``.EXE'' will be used as the target in the absence of this statement. % \item[\bf \#LINK\_SWITCHES {\em Link\_Qualifier\_Switches}] \hfill \\ This construct is used if specific LINK qualifiers must appear on the LINK statement to build the image described by this IMGDEF file. These qualifiers will appear after the \$(LINKFLAGS) macro in the MMS action line, thus overriding any default values or command line definitions. % \item[\bf \#! {\em comment text ...} ] \hfill \\ This allows the use of IMGDEF comments, which are not passed to the output files. % \item[\bf \#OPTION\_ONLY ] \hfill \\ This construct overrides any command line options with respect to creating MMS files. It is a safeguard for those special case IMGDEF files which must only generate options files (mostly in SH). % \end{description} These \#IMGDEF directives are all optional, in which case the input is viewed as nothing more than a VMS options file. MMS files are still output, but defaults are used which may or may not be acceptable. \section{An Example} Here is an example of an image definition file and the output files generated from IMGDEF. Generic names are used, with SOGS conventions. \pagebreak[3] \begin{verbatim} #! #! program.IMGDEF -- Image definition file for program #! #INCLUDE SOGSTOOLS:STD_BLD.IMGDEF #TARGET subsystem_EXE:program.EXE #REQUIRE AFTER SH_SOURCE:SOGS_KERNEL.OPT subsystem_OBJECT:program.OBJ subsystem_OBJECT:program_SUB1.OBJ subsystem_OBJECT:program_SUB2.OBJ ... #INCLUDE subsystem_SOURCE:subsystem_KERNEL.IMGDEF \end{verbatim} IMGDEF will copy all of the non-\# statements above into the program.OPT file as well as the contents of any \#INCLUDE files, i.e., \begin{verbatim} subsystem_OBJECT:program.OBJ subsystem_OBJECT:program_SUB1.OBJ subsystem_OBJECT:program_SUB2.OBJ ... subsystem_EXE:FNsubsystem.EXE/SHARE ! kernel News (from #INCLUDE) subsystem_EXE:FNsubsystem.STB/SELECTIVE ... \end{verbatim} \pagebreak[3] The program\_LNK.MMS file will look like this: \begin{verbatim} subsystem_EXE:program.EXE : - subsystem_OBJECT:program.OBJ, - subsystem_OBJECT:program_SUB1.OBJ, - subsystem_OBJECT:program_SUB2.OBJ, - ... subsystem_EXE:FNsubsystem.EXE, - subsystem_EXE:FNsubsystem.STB, - ... subsystem_SOURCE:program.OPT, - SH_SOURCE:SOGS_KERNEL.OPT ! $(LINK) $(LINKFLAGS) /EXE=subsystem_EXE:program.EXE - subsystem_SOURCE:program.OPT/OPTION, - SH_SOURCE:SOGS_KERNEL.OPT/OPTION \end{verbatim} The program\_BLD.MMS will simply .INCLUDE the necessary \_LNK and \_COMPILE MMS files, i.e., \begin{verbatim} ! (Standard build-MMS header lines ! .INCLUDE subsystem_MMS_BUILD:program_LNK.MMS .INCLUDE subsystem_MMS_BUILD:program_COMPILE.MMS .INCLUDE subsystem_MMS_BUILD:program_SUB1_COMPILE.MMS .INCLUDE subsystem_MMS_BUILD:program_SUBs_COMPILE.MMS ... \end{verbatim} For the .INCLUDE-ing of the \_COMPILE.MMS files above, the subsystem is taken from the object file specification, not the command line or the target. \section{Conversion of Old Build Files} The output files above are similar to methods used before, but now all the build information is contained in a single file. This will be the only build file for an image that is configured in CMS. The MMS and options files will be generated as needed, with copies remaining in the baseline directories. To get the previous MMS and options files into image definition format, a conversion tool (CNV) was developed. This tool picks off the pieces it needs from the old \_LINK MMS files and the options files, adding the necessary standard items into the new image definition file. References to vendor software libraries are made consistent, using \#REQUIRE directives at the end of the IMGDEF file. For SOGS, references to the SH areas are removed and superceded by new \#REQUIREd options files or \#INCLUDEd IMGDEF files. \section{SOGS Build Procedures} As described above and shown in the example, the SOGS build procedures have been made more consistent. Standard options and include files have been generated for SOGS-wide, subsystem-wide, and vendor references. All references to SH software will be through the two options files, SOGS\_NON\_KERNEL.OPT and SOGS\_KERNEL.OPT, making future changes in SH transparent to subsystem build files. Subsystems need not know whether they are linking to libraries, shareable images, or explicit objects in the SH area, as long as things are built correctly. Subsystem developers can extend this approach further to subsystem-wide references. As part of the News delivery, the subsystem\_KERNEL.IMGDEF files will contain references to the kernel News files. All vendor software will be referenced through \#REQUIRE files, namely: \begin{verbatim} #REQUIRE AFTER SOGSTOOLS:DEANZA.OPT #REQUIRE AFTER SOGSTOOLS:DISPLA.OPT #REQUIRE AFTER SOGSTOOLS:IMSL.OPT #REQUIRE AFTER SOGSTOOLS:NAG.OPT #REQUIRE AFTER SOGSTOOLS:OMNIBASE.OPT #REQUIRE AFTER SOGSTOOLS:ZETA.OPT \end{verbatim} The details of linking to a specific vendor library will now reside in a single file. Should something change, say in Omnibase, only that IMGDEF file needs to be changed, not every MMS and options file in SOGS that references it. A separate MMS file will make sure that these options files are up-to-date with respect to their contents. \section{From Now On} With IMGDEF in place, only the .IMGDEF files need to be configured in the CMS libraries. For any given program, the options and MMS build and link files will be automatically generated from the .IMGDEF file. These will be regenerated whenever the .IMGDEF file changes or one of its \#INCLUDE files changes. The use of IMGDEF does not remove the need for {\it all} MMS files. Most of these can now be generated automatically by IMGDEF, but the top-level {\it driver} MMS files and the low-level \_COMPILE.MMS files will continue to be manually maintained or generated by other tools (e.g., MAKE\_COMPILE\_MMS.COM in DEVTOOLS). All options files have been converted to IMGDEF format, even if only to use the \#OPTION\_ONLY construct. \section{Future Enhancements} Parts of IMGDEF are SOGS-dependent, out of necessity for the short-term needs of SOGS (i.e., delivery of the News project). There was little effort made to find out the true needs of other systems supported by OSB. The build concepts should be largely transportable, although some may be overkill for other OSB systems. Additional changes to IMGDEF will most likely be required for such support. A limitation in IMGDEF currently is the lack of support for library module references, e.g., the MMS-style LIB.OLB(MODULE) and the LINK-style LIB.OLB/INCLUDE=(MODULE,...). Our current approach in SOGS is to list the library as an MMS dependency and relink if it is newer than the executable. This is safe, but can be wasteful if the program needs only one module from the library. Another limitation is that the \_LNK.MMS files do not provide much flexibility. IMGDEF provides only one method for linking an image, although any link qualifier may be used. This means that link files cannot be generated which require anything more than the standard LINK statement, e.g., to link for a .EXE file and then for a .STB file, which requires two separate statements in the \_LNK.MMS. SH and PODPS currently require such support. Initially, those MMS files will remain manually-maintained as opposed to IMGDEF-generated; the options files will be IMGDEF-generated, with the \#OPTION\_ONLY directive being used. Other features will undoubtedly be put on the ``wish-list'' once we get more experience building SOGS with IMGDEF-generated MMS and options files. \pagebreak[3] \section{Appendix} Here is an honest-to-goodness working IMGDEF file from Support Software. *** RAINPT.IMDEF \begin{verbatim} #INCLUDE SOGSTOOLS:STD_BLD.IMGDEF #TARGET SS_EXE:RAINPT.EXE #REQUIRE BEFORE SH_SOURCE:FAHWOPT.OPT #REQUIRE BEFORE SS_SOURCE:FDSS.OPT #REQUIRE AFTER SH_SOURCE:SOGS_KERNEL.OPT SS_OBJECT:RAINPT.OBJ,- SS_OBJECT:RAITEST.OBJ #INCLUDE SS_SOURCE:SS_KERNEL.IMGDEF \end{verbatim} *** RAINPT.OPT \begin{verbatim} SS_OBJECT:RAINPT.OBJ,- SS_OBJECT:RAITEST.OBJ \end{verbatim} *** RAINPT\_BLD.MMS \begin{verbatim} !*** ! ! Standard MMS header for SOGS _BLD files. ! INCLUDE SOGSTOOLS:SOGSMMSDEFS.MMS ! Standard definitions for all SOGS MMS ! .FIRST INCLUDE SOGSTOOLS:SOGS1STDEFS.MMS ! Standard "FIRST" actions for SOGS MMS ! .LAST INCLUDE SOGSTOOLS:SOGSENDDEFS.MMS ! Standard "LAST" actions for SOGS MMS ! !*** .INCLUDE SS_MMS_BUILD:RAINPT_LNK.MMS .INCLUDE SS_MMS_BUILD:RAINPT_COMPILE.MMS .INCLUDE SS_MMS_BUILD:RAITEST_COMPILE.MMS \end{verbatim} *** RAINPT\_LNK.MMS \begin{verbatim} SS_EXE:RAINPT.EXE : - SS_OBJECT:RAINPT.OBJ, - SS_OBJECT:RAITEST.OBJ, - SH_SOURCE:FAHWOPT.OPT, - SS_SOURCE:FDSS.OPT, - SS_SOURCE:RAINPT.OPT, - SH_SOURCE:SOGS_KERNEL.OPT ! $(LINK) $(LINKFLAGS) /EXECUTABLE=SS_EXE:RAINPT.EXE - SH_SOURCE:FAHWOPT.OPT/OPTIONS, - SS_SOURCE:FDSS.OPT/OPTIONS, - SS_SOURCE:RAINPT.OPT/OPTIONS, - SH_SOURCE:SOGS_KERNEL.OPT/OPTIONS \end{verbatim} \end{document}