% Librarian A09-10X0~0+,5 MAKE~01 MAKEF MAKE/VMS is a utility which performs commands specified by the userF when a dependency relationship specified by the user is notF satisfied. This is useful in situations such as software developmentF where the user is in an edit-compile-test cycle and wishes toF simplify the steps between 'edit' and 'test'. Many other tasks lend' themselves well to the MAKE structure." $ MAKE [Qualifier(s)] [Target(s)] 2 Qualifiers /INPUT=? Choos e an alternate makefile. The default value is "MAKEFILE"./OUTPUT=F Specify the name of the command file. Use '/KEEP' also if you& actually wish for the file to remain./DEBUG /DEBUG /NODEBUG (default)F Print debugging info (for bug reports). Much of the action of MAKE# may be discerned from this output. /DEFAULTS /DEFAULTS (default) /NODEFAULTSE Control reading of the default rules file MAKE_DEFAULTS or MAKE.INI./DEFINE) /DEFINE=("symbol1","sym bol1=value1",...)# Define symbols prior to execution./EXECUTE /EXECUTE (default) /NOEXECUTEF Execute the commands needed to update the targets. The negation ofF this qualifier is useful in order to obtain a static command file viaF a combination of qualifiers such as /KEEP, /FORCE, and /OUTPUT for later use./FORCE7 Always rebuild all targets, even if they are in synch./IGNORE /IGNORE /NOIGNORE (default)@ Ignore errors in the command file (via the comman d 'SET NOON')./KEEP /KEEP /NOKEEP (default)@ Prevent deletion of the command file generated by running MAKE./MACRO& /MACRO=("file1","symbol1=value1",...)B Define symbols either directly or from a file prior to execution./SPAWN /SPAWN /NOSPAWN (default)F The default action of MAKE is to call the routine LIB$DO_COMMAND toF execute the command file (if any) that has been built during the MakeF phase. Use of this qualifier directs MAKE to perform a SPAWN/NOWAIT i nstead./VERIFY /VERIFY /NOVERIFY (default)> Echo commands as they execute (via the command 'SET VERIFY'). 2 DescriptionF MAKE is a program which reads a file of dependencies and executesF commands when one file is out of date with respect to one or moreF files upon which it depends. For instance, an executable imageF FOO.EXE depends upon FOO.OBJ, which in turn depends upon FOO.C andF FOO.H. If FOO.H is modified, then it is newer than FOO.OBJ and soF FOO.OBJ needs to be remade. Because FOO.OBJ is remade, FOO.EXE willF become out of date and must be remade subsequently. MAKE readsF user-supplied description files and executes any commands required to? bring the target(s) up to date with respect to all dependents. 3 ParsingF MAKE takes as input one or more description files which,F appropriately enough, describe the relationships between targets andF sources. An attempt is made to open the file MAKE_DEFAULTS, which mayF be a logical name. If this fails, the file MAKE.INI in the currentF directory is attempted. After the initialization file is parsedF (only the first encountered will be used), an attempt is made to openF MAKEFILE. This, too, may be a logical name. Alternatively, it may beF specified on the command line with the /INPUT qualifier. There is noF explicit requirement to access a makefile successfully, but theF requirement of finding at least one target implicitly requires at# least  one makefile to be accessed.F As the files are read in line by line, they are internalized into theF various data structures used by MAKE, such as the Symbol list, theF Target list, the File list, et al. Output from the /DEBUG qualifier/ demonstrates the parsing phase in gory detail.3 MakingF After all makefiles have been digested, one or more targets areF 'made'. If any targets were specified on the command line, each isF 'made' in turn. If no targets were specified, the  first bona fide7 target encountered during the parsing phase is 'made'.F A target is 'made' by making in turn each of its prerequisites. IfF you are thinking that this is a recursive definition, you mightF consider becoming a programmer. When MAKE reaches the end of aF branch, it climbs back down a level in the tree comparing the date ofF the current level's target to the newest dependent. If a target isF older than at least one of its prerequisites (and a missing targe t isF considered infinitely old), it is 'built' according to the commands< that were supplied with the dependency rule being examined.F A target is out of date if it is newer than a dependent, butF obviously the more general case has a target out of date if it doesF not even exist. Also, one can create a target that has noF dependents, a so-called 'terminal target'. Terminal targets exist orF don't exist, but can't be out of date. If a terminal target does notF exi st, it will be 'built' (the commands for the target will be addedF to the command file). If it exists, fine. If any dependent of aF target is built, then the target must be built as well. Since theF 'making' is recursive, the leaves of the tree are checked before theF branches so that this forces 'building' to propagate back to the root target.4 Normal_filesF The comparison date for normal files is the revision date of the fileF as returned by the VAXCRTL 'stat' function. Thi s can be examined( from DCL using the DIR/DAT=MOD command.4 Library_modulesF The comparison date for library modules (syntax = 'lib.typ(mod)') isF the date of last modification of the module as returned by theF LBR$SET_MODULE routine. Note that libraries may be of any typeC acceptable to the VAX Librarian facility (.OLB, .TLB, .MLB, etc.).4 CMS_elementsF The comparison date for CMS elements is the date of last modificationF for the generation of the element in the speci fied class, or theF newest generation along the main line of descent if no class is specified. 3 BuildingF Building a target consists of placing the commands, suitablyF formatted, into a command file for later execution. When the MakeF phase completes, the command file is closed and it is executed (usingF LIB$DO_COMMAND) in the current process, unless the /SPAWN qualifierF was specified or the %SPAWN directive was encountered without aF countermanding %NOSPAWN.  Simple error handling is included in theF command file to cause command processing to terminate when an errorF (DCL ERROR severity) is encountered. Also, the command file containsF a command to delete itself upon exiting. This can be prevented via the /KEEP qualifier.2 SyntaxF The description file is called a 'MAKEFILE', as in the UNIX version.F Lines in a VMS makefile fall into four categories: target lines,, command lines, symbol lines, or directives.3 DependenciesF Target lines must begin at column one (no preceding whitespace). TheF colon separating the targets from the prerequisites must be followedF by at least one whitespace. Targets and prerequisites may beF separated from each other by commas and/or whitespace. Because commasF are simply replaced with whitespace in a target line, two commas in aF row do not signify a null target. If a target or prerequisite has aF qualifier attached ('/junk'), the qualifier is removed from theF modul e name. This allows a symbol to be used in both target lines andF command lines. For instance, you may have a symbol defined as theF list of LINK options files, with each options file followed by theF qualifier '/OPT'. This way, you can use the symbol in the target line AND the LINK command. 3 Objects4 Normal_filesF There are no tricks to specifying a normal file. Use the standard VMS4 syntax as described in the DCL Dictionary (et al.).4 Library_modulesF A name like 'a.olb(b)' means the module named 'b' stored in theF library named 'a.olb'. This name is handled just like a normal fileF name, except that a special routine is entered to read theF modification time of the module in the library. If the libraryF doesn't exist, then it is made. If there is a rule for creating the library, such as: ################### a.olb : # lib/cre a # ###################F then it will be created. Otherwise, an error is signalled since theF library couldn't be found. The default library type is '.OLB' if noF type is specified (this is the VAX Librarian's default). Note thatF you can use a default rule to create the library if it doesn't exist: ########################## *.olb : # lib/cre $* # *.hlb : # lib/help/cre $* # *.tlb : # lib/cre/text $* # ##########################4 CMS_library_modulesF A CMS module is specified as the element name followed by t he '~'F (tilde) character, optionally followed by a CMS library name. You canF specify a default CMS library using the '%CMSLIB' directive. ForF example, the element FOO.C in library [.CMS] would be 'FOO.C~[.CMS]'.3 Default_rulesF When dealing with complex programs, it is not reasonable to listF explicitly rules for compilation of every module. Rather, one wouldF like to be able to say "If X.Obj is out of date, go look for X.C andF compile it, regardless of who X is." This feature is provided by the default rules mechanism: ####################2 *.obj : *.c # '$*' is a symbol which means/ cc $* # 'whatever matched the *'. ####################F With the above makefile, we may compile any C program (FOO) by givingF the DCL command '$ make foo.obj'. The default rule will match theA '*' with 'foo' and will insert '$ cc foo' into the command file.F The default rules will be searched for a pattern match only if eitherF there are no rules for the file in question or there are rules but noF command lines. If a match is found, the default rules will be addedF just as though they were found explicitly in the makefile. TheF symbol '$*' expands to the root name (the part that matches theF wildcard), '$@' expands to the name of the target, and '$<' expandsF to the name of the prerequisite. '$?' expands to the list of allF the prerequisites whose date information forced the target to beF built. In the  case of multiple rules for a target, the first ruleF for which the prerequisite _exists_ will be used. If no rule has anB existing prerequisite, then the first matching rule will be used.F The wildcard character '*' does not have to be the first character inF the target. You might want to have your sources and objects inF different directories, for example. The following rule epitomizes the flexibility of wildcards: [OBJ]*.obj: [SRC]*.c cc $ symbol __ALPHA is define when MAKE is run on Alpha platforms. 3 DirectivesF Directives are signified by a '%' in column one. There can not beF whitespace between the '%' and the directive name. Some directivesF take argum #ents, which must be separated by whitespace from the directive name.4 IFDEF_F Subsequent commands are executed only if is defined. ThisF processing state will exist until a matching ELSE, ELIFDEF, ELIFNDEF,D or ENDIF is encountered. These commands may be nested to any depth.4 IFNDEF_F Subsequent commands are executed only if is not defined.F This processing state will exist until a matching ELSE, ELIFDEF,F ELIFNDEF, or ENDIF is encounter$ed. These commands may be nested to any depth.4 ENDIFF Terminates the processing state established by a previous IFDEF or IFNDEF directive.4 ELSEF Inverts the processing state caused by a previous IFDEF, IFNDEF, ELIFDEF, or ELIFNDEF directive.4 ELIFDEF_F The processing state established by the closest previous IFDEF,F IFNDEF, ELIFDEF, or ELIFNDEF is overridden; subsequent commands will* be executed only if is defined. 4 ELIFNDEF_F The %processing state established by the closest previous IFDEF,F IFNDEF, ELIFDEF, or ELIFNDEF is overridden; subsequent commands will. be executed only if is not defined. 4 INCLUDE_9 Causes the parsing routine to digest the specified file.4 CMSLIB_< Selects the specified directory as the default CMS library.4 CMSGEN_C Specifies the generation to be used for determining element dates.4 DEBUG= Turn on debugging (similar to the /DEBUG command qual&ifier). 4 NODEBUG@ Turn off debugging (similar to the /NODEBUG command qualifier).4 SPAWN? Direct MAKE to spawn the command file at the end of execution. 4 NOSPAWNF Direct MAKE to execute the command file in the current process at the end of execution. 3 Example2 # <== This is a comment indicator (in column one) ! <== As is thisD %SPAWN !Force the command file to be spawned at the end of making1 foo.exe: foo.obj # This is a target line 6 link foo # This 'is a DCL command line @ foo.obj: foo.c foo.h ! <== This is also a comment indicator  cc/lis foo 0 As a human would read the description, it says:F "FOO.EXE depends upon FOO.OBJ. If FOO.EXE is out of date or FOO.OBJF has been 'made', then add the command 'LINK FOO' to a file ofF commands to be executed. FOO.OBJ depends upon FOO.C and FOO.H. IfF it is out of date, or either of its dependents have been 'made', then6 add 'CC/LIS FOO' to the command file to be execut (ed." 2 MakefilesF MAKE tries to locate two description files. The first is nominallyF the default rules file, while the second is the 'main' descriptionF file. In reality, there is no internal distinction between the twoF files. No error is reported if neither file is found. An errorF during the MAKE phase will be displayed: if you specify a target onF the command line and it exists, nothing happens; if the target isF missing, the error is "target doesn't exist and c )ouldn't be made"F since there are no rules; if no target was specified on the command9 line, then MAKE has no target and complains accordingly.3 Default_rulesF The first file which MAKE attempts to locate is a description of theF default rules to be applied when no explicit rules for a target areF provided. Two attempts are made to locate a default rules file.F First, the file "MAKE_DEFAULTS" (which may be a logical name) isF tried. If the open fails on this file, MAKE * tries for the file "MAKE.INI". 3 MakefileF The second file which MAKE attempts to locate is "MAKEFILE", whichF may be a logical name. You may also specify this file on the command! line via the '/INPUT' qualifier.2 General_AdviceF The Makefile that comes with MAKE/VMS is a very good example of whatF can be done with the system. Also, UNIX makefiles are fairly usefulF to examine, but obviously the command lines will be different. Also,F since it is horribly inefficient in VMS to + spawn a subprocess forF each command, there is a fundamental difference between the operationF on VMS and UNIX. UNIX MAKE spins off a new process for each command,F but MAKE/VMS builds a command file and defers execution until theF end. I like my way much better, but I have the advantage ofF hindsight. Of course, there are some significant drawbacks to the batch method, too.2 Bugs' There are always bugs. Report bugs to: Ned Freed" Innosoft International, Inc. Claremont, CA 91711 ned@innosoft.com6 ******** Please include /DEBUG output. *********ww