
		IMGDEF  --  Image Definition Facility

(This information is extracted from the IMGDEF User's Guide -- V1.0, 5/11/88,
 which is located in OSBDOC_SS:IMGDEF.TEX.)


SYNOPSIS

	An image definition file contains the information on how to build an
	executable image.  It is the primary input to IMGDEF, which is used
	to produce an options file, an MMS file to describe the LINK process,
	and an MMS file for building the image and its components. 


COMMAND SETUP

	IMGDEF is a program in SOGSTOOLS and is run from DCL.  The command
	is defined in SOGSTOOLS:BUILDSOGS_LOGIN.COM or as follows:

	$ IMGDEF :== $SOGSTOOLS:IMGDEF.EXE


USAGE

        $ 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)


    The subsystem parameter is used to determine where the output files
    will be created.  For example,

                $ IMGDEF name.IMGDEF subsystem

    will produce as output:

                subsystem_SOURCE:name.OPT
                subsystem_MMS_BUILD:name_LNK.MMS
                subsystem_MMS_BUILD:name_BLD.MMS

    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 the output files may not
    be completely correct, but it can serve as a test of the IMGDEF file.


IMGDEF 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:


    #REQUIRE { BEFORE | AFTER } options_file_name

        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.

    #INCLUDE IMGDEF_file_name

        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 #INCLUDE
        constructs. The IMGDEF processor will initially impose an include
        nesting limit of 3, to prevent run-away.

    #DEFINE symbol_name "replacement_string"

        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.)

    #(symbol_name)

        This construct is used to substitute the replacement string defined
        by a previous #DEFINE statement for the symbol_name.

        The #( ) can appear on any non-# lines within an IMGDEF file.

    #MMS_BEGIN { BUILD | LINK }

        . . . MMS statements . . .

    #MMS_END

        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 #MMS_END must appear within the
        IMGDEF file following a #MMS_BEGIN statement. If the #MMS_END is
        missing, the processor will generate an error.

    #TARGET Target_file_name

        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.

    #LINK_SWITCHES Link_Qualifier_Switches

        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.

    #! comment text ...

        This allows the use of IMGDEF comments, which are not passed
        to the output files.

    #OPTION_ONLY

        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).


    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.


EXAMPLE

    Here is an example of an image definition file and the output files
    generated from IMGDEF.  Generic names are used, with SOGS conventions.

        #!
        #!  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


    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.,

        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
        ...


    The program_LNK.MMS file will look like this:

        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


    The program_BLD.MMS will simply .INCLUDE the necessary _LNK and _COMPILE
    MMS files, i.e.,

        ! (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

        ...


    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.


VENDOR REFERENCES

    All vendor software will be referenced through #REQUIRE files, namely:

                #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


ACTUAL EXAMPLE (FROM SUPPORT SOFTWARE)


*** RAINPT.IMDEF

	#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


*** RAINPT.OPT

	SS_OBJECT:RAINPT.OBJ,-
	SS_OBJECT:RAITEST.OBJ


*** RAINPT_BLD.MMS

	!***
	!
	!  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


*** RAINPT_LNK.MMS

	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
