diff options
Diffstat (limited to 'unix/boot/mkpkg/mkpkg.hlp')
| -rw-r--r-- | unix/boot/mkpkg/mkpkg.hlp | 626 |
1 files changed, 626 insertions, 0 deletions
diff --git a/unix/boot/mkpkg/mkpkg.hlp b/unix/boot/mkpkg/mkpkg.hlp new file mode 100644 index 00000000..39dd1163 --- /dev/null +++ b/unix/boot/mkpkg/mkpkg.hlp @@ -0,0 +1,626 @@ +.help mkpkg Mar90 "softools" +.ih +NAME +mkpkg - make or update a package or library +.ih +USAGE +mkpkg [switches] [module ...] [name=value ...] +.ih +ARGUMENTS +.ls 10 \fB-d[ddd]\fR +Debug mode. Print detailed messages describing what \fImkpkg\fR is doing. +There are four levels of debug messages, selected by repeating the "d" +character in the switch, e.g., "-d" is level one, "-dd" is level two, and +so on. The debug messages get progressively more detailed as the debug level +increases. Debug mode automatically enables the verbose mode messages. +.le +.ls 10 \fB-f file\fR +Set the name of the file to be interpreted (default: "mkpkg"). +The special value "stdin" (lower case) allows commands to be entered +interactively from the standard input, e.g., for debugging \fImkpkg\fR. +.le +.ls 10 \fB-i\fR +Ignore errors. Execution continues even if an error occurs. In most cases +it does anyhow, so this switch has little effect at present. +.le +.ls 10 \fB-n\fR +No execute. Go through the motions, but do not touch any files. +No execute mode automatically enables verbose mode (flag "-v"). +This switch should be used to verify new mkpkg files before execution. +.le +.ls 10 \fB-p \fIpkgname\fR +Load the package environment for the named external package, e.g., +"mkpkg -p noao update". If the same package is always specified +the environment variable or logical name PKGENV may be defined at the +host level to accomplish the same thing. The package name \fImust\fR +be specified when doing software development in an external or layered +package. +.le +.ls 10 \fB-u\fR [AOSVS/IRAF only] +Forcibly update the dates of improperly dated library modules. This option +is used when a binary archive is restored on a machine which cannot restore +the file modify dates. In this case, all source file dates would appear to +have been modified since the libraries were updated, causing all sources to +be recompiled. By running \fImkpkg\fR with the \fI-u\fR flag, one can update +the library module dates without recompiling the associated files. This is +done by setting the date of each library module to be no older than the +file \fIhlib$iraf.h\fR, which should be "touched" after the system has fully +been restored to disk to mark the installation time. Note that files which +have been modified \fIsince\fR the system was restored to disk will still +cause the affected library modules to be updated, even when the \fI-u\fR flag +is specfied. +.le +.ls 10 \fB-v\fR +Verbose mode. A message is printed whenever a file is touched. +Recommended when running large mkpkg jobs in batch mode. +.le +.ls 10 \fBmodule\fR +The names of the module or modules (named entries in the "mkpkg" file) to be +executed. If no module is named the first module encountered is executed, +unless a \fImkpkg\fR macro preprocessor directive at the beginning of the file +specifies a different default action. +.le +.ls 10 \fBname=value [name=value...]\fR +Enter the named symbol/value pair into the symbol table of the \fImkpkg\fR +macro preprocessor. The symbols \fIXFLAGS\fR (for the XC compiler) and +\fILFLAGS\fR (for the linker) are predefined but may be redefined on the +command line. Case is ignored in symbol names for portability reasons. +.le +.ih +DESCRIPTION +The \fImkpkg\fR utility is used to make or update IRAF packages or libraries. +\fIMkpkg\fR is used to bootstrap the IRAF system hence is implemented as +a foreign task, callable either from within the IRAF environment or from the +host system. Usage is identical in either case (except that the details of +when a particular argument may need to be quoted will vary depending on the +command language used). \fIMkpkg\fR is upwards compatible with the old +\fImklib\fR utility. + + +.tp 4 +1. \fBIntroduction\fR + + \fIMkpkg\fR provides two major facilities: a library update capability and +a macro preprocessor. The macro preprocessor provides symbol definition and +replacement, conditional execution, and a number of builtin commands. +The usefulness of these facilities is enhanced by the ability of \fImkpkg\fR +to update entire directory trees, or to enter the hierarchy of \fImkpkg\fR +descriptors at any level. For example, typing "mkpkg" in the root directory +of IRAF will make or update the entire system, whereas in the "iraf$sys" +directory \fImkpkg\fR will update only the system libraries, and in the +"iraf$sys/fio" directory \fImkpkg\fR will update only the FIO portion of the +system library "libsys.a". + +The \fImkpkg\fR utility is quite simple to use to maintain small packages +or libraries, despite the complexity of the discussion which follows. +The reader is encouraged to study several examples of working mkpkg-files +before reading further; examples will be found throughout the IRAF system. +The mkpkg files for applications packages tend to be very similar to one +another, and it is quite possible to successfully copy and modify the +mkpkg-file from another package without studying the reference information +given here. + + +.tp 4 +2. \fBLexical Conventions\fR + + The lexical conventions employed in \fImkpkg\fR are those used throughout +IRAF. Comments may occur anywhere, begin with the character #, and extend +to the end of the current line. Blank lines are ignored virtually everywhere. +Newline may be escaped with backslash to continue on the next line. +All filenames are IRAF virtual filenames with the following extensions. + + +.ks +.nf + .a object library + .c C source + .e executable (e.g., "x_package.e") + .f Fortran source + .gc generic C source + .gx generic SPP source + .h C or SPP header file + .inc include file + .l Lex source + .o object file + .r Ratfor source + .s assembler source + .y Yacc source +.fi +.ke + + +Since \fImkpkg\fR is an IRAF utility it recognizes the major IRAF logical +directories; these are summarized in the list below. The IRAF (or UNIX) +pathname convention is used to specify pathnames rooted in the current +directory or a logical directory. + + +.ks +.nf + as$ where .s files go host$as/ + bin$ installed executables iraf$bin/ + dev$ device tables iraf$dev/ + hlib$ machdep header files host$hlib/ + host$ host system interface [MACHDEP] + iraf$ the root directory of IRAF [MACHDEP] + lib$ system library iraf$lib/ + math$ math sources iraf$math/ + pkg$ applications packages iraf$pkg/ + sys$ the VOS, system libraries iraf$sys/ + tmp$ where temporary files go [MACHDEP] +.fi +.ke + + +All other directories should be referenced by giving the path from either the +current directory or from one of the system logical directories shown above. +For example, "pkg$system/" is the root directory of the SYSTEM package, +and ".." is the directory one level up from the current directory. + + +.tp 4 +3. \fBMaintaining Libraries with MKPKG\fR + + Libraries are described by a \fBmember list\fR module in the "mkpkg" file. +The syntax of a library member list module is shown below. Note that the +\fBmkpkg\fR module name for a library member list module is the same as the +name of the actual library, hence must end with the extension ".a". + + +.ks +.nf + libname.a: + member1 dep1 dep2 ... depN + member2 dep1 dep2 ... depN + ... + memberN dep1 dep2 ... depN + ; +.fi +.ke + + +Here, "libname.a" is the IRAF virtual filename of the library (regardless of +what directory it resides in), "memberN" is the name of a source file which +may contain any number of actual library object modules, and "depN" is the +name of a file upon which the named member depends. If any of the named +dependency files is newer than the corresponding member source file, or if +the member source file is newer than the compiled library object module, +the source file is recompiled and replaced in the library. Both source +files and dependency files may reside in remote directories. The names of +dependency files in system libraries should be enclosed in <> delimiters, +e.g., "<fset.h>". Each member must be described on a separate line. + +If the library being updated does not reside in the current directory +(directory from which the "mkpkg" command was entered) then the library must +be "checked out" of the remote directory before it can be updated, and checked +back in when updating is complete. These operations are performed by macro +preprocessor directives, e.g.: + + +.ks +.nf + $checkout libsys.a lib$ + $update libsys.a + $checkin libsys.a lib$ + $exit + + libsys.a: + @symtab # update libsys.a in ./symtab + brktime.x <time.h> + environ.x environ.com environ.h <ctype.h>\ + <fset.h> <knet.h> + main.x <clset.h> <config.h> <ctype.h>\ + <error.h> <fset.h> <knet.h>\ + <printf.h> <xwhen.h> + onentry.x <clset.h> <fset.h> <knet.h> + spline.x <math.h> <math/interp.h> + ; +.fi +.ke + + +Note that the checkout operation is required only in the directory from which +the "mkpkg" command was entered, since the library has already been checked +out when the mkpkg-file in a subdirectory is called to update its portion +of the library (as in the "@symtab" in the example above). The checkout +commands should however be included in each mkpkg-file in a hierarchy in such +a way that the library will be automatically checked out and back in if +\fImkpkg\fR is run from that directory. The checkout commands are ignored +if the mkpkg-file is entered when updating the library from a higher level, +because in that case \fImkpkg\fR will search for the named entry for the +library being updated, ignoring the remainder of the mkpkg-file. + +Sometimes it is necessary or desirable to break the library member list up +into separate modules within the same mkpkg-file, e.g., to temporarily +change the value of the symbol XFLAGS when compiling certain modules. +To do this use the "@" indirection operator in the primary module list to +reference a named sublist, as in the example below. Normal indirection +cannot be used unless the sublist resides in a subdirectory or in a different +file in the current directory, e.g., "@./mki2", since a single mkpkg-file +cannot contain two modules with the same name. The same restrictions apply +to the \fI$update\fR operator. + + +.ks +.nf + libpkg.a: + @(i2) + alpha.x + beta.x + zeta.f + ; + i2: + $set XFLAGS = "-cO -i2" + gamma.f + delta.f + ; +.fi +.ke + + +In the example above five object modules are to be updated in the library +"libpkg.a". The files listed in module "i2", if out of date, will be compiled +with the nonstandard XFLAGS (compiler flags) specified by the \fI$set\fR +statement shown. + + +.tp 4 +4. \fBThe MKPKG Macro Preprocessor\fR + + The \fImkpkg\fR macro preprocessor provides a simple recursive symbol +definition and replacement facility, an include file facility, conditional +execution facilities, an OS escape facility, and a number of builtin directives. +The names of the preprocessor directives always begin with a dollar sign; +whitespace is not permitted between the dollar sign and the remainder of the +name. Several preprocessor directives may be given on one line if desired. +Preprocessor directives are executed as they are encountered, and may appear +anywhere, even in the member list for a library. + + +.tp 4 +4.1 Symbol Replacement + + Symbol substitution in the \fImkpkg\fR macro preprocessor is carried out +at the character level rather than at the token level, allowing macro expansion +within tokens, quoted strings, or OS escape commands. Macros are recursively +expanded but may not have arguments. + +Macros may be defined on the \fBmkpkg\fR command line, in the argument list +to a \fB$call\fR or \fB$update\fR directive (see below), in an include file +referenced with the \fB$include\fR directive, or in a \fB$set\fR directive. +All symbols are global and hence available to all lower level modules, +but symbols are automatically discarded whenever a module exits, hence cannot +affect higher level modules. A local symbol may redefine a previously +defined symbol. The IRAF and host system environment is treated as an +extension of the \fBmkpkg\fR symbol table, i.e., a logical directory such +as "iraf" may be referenced like a locally defined symbol. + +Macro replacement occurs only when explicitly indicated in the input text, +as in the following example, which prints the pathname of the +\fBdev$graphcap\fR file on the \fBmkpkg\fR standard output. The sequence +"$(" triggers macro substitution. The value of a symbol may be obtained +interactively from the standard input by adding a question mark after the +left parenthesis, i.e., "$(?terminal)" (this does not work with the -f stdin +flag). The contents of a file may be included using the notation +"$(@\fIfile\fR)". Note that case is ignored in macro names; by convention, +logical directories are normally given in lower case, and locally defined +symbols in upper case. + + +.ks +.nf + $echo $(dev)graphcap + !xc $(XFLAGS) filea.x fileb.x +.fi +.ke + + +Symbols are most commonly defined locally with the \fB$set\fR directive. +The \fB$include\fR directive is useful for sharing symbols amongst different +modules, or for isolating any machine dependent definitions in a separate +file. The IRAF \fBmkpkg\fR system include file \fBhlib$mkpkg.inc\fR is +automatically included whenever \fImkpkg\fR is run. +.ls 4 +.ls \fB$set\fR symbol = value +Enter the named symbol into the symbol table with the given string value. +Any existing symbol will be silently redefined. Symbols defined within a +module are discarded when the module exits. +.le +.ls \fB$include\fR filename +Read commands (e.g., \fB$set\fR directives) from the named include file. +The include filename may be any legal virtual filename, but only the +major logical directories are recognized, e.g., "iraf$", "host$", "hlib$", +"lib$", "pkg$", and so on. +.le +.le + + +The use of the \fB$set\fR directive is illustrated in the example below. +Note the doubling of the preprocessor meta-character to avoid macro expansion +when entering the value of the GEN macro into the symbol table. The sequence +"$$" is replaced by a single "$" whenever it is encountered in the input +stream. + + +.ks +.nf + $set GFLAGS = "-k -t silrdx -p ak/" + $set GEN = "$generic $$(GFLAGS)" + + ifolder (amulr.x, amul.x) $(GEN) amul.x $endif +.fi +.ke + + +.tp 4 +4.2 Conditional Execution + + Conditional control flow is implemented by the \fB$if\fR directives +introduced in the last example and described below. The character "n" may +be inserted after the "$if" prefix of any directive to negate the sense of +the test, e.g., "$ifndef" tests whether the named symbol does not exist. +Nesting is permitted. +.ls 4 +.ls \fB$ifdef\fR (symbol [, symbol, ...]) +.sp +Test for the existence of one of the named symbols. +.le +.ls \fB$ifeq\fR (symbol, value [, value,...]) +.sp +Test if the value of the named symbol matches one of the listed value strings. +.le +.ls \fB$iferr\fR +.sp +Test for an error return from the last directive executed which touched +a file. +.le +.ls \fB$iffile\fR (file [, file,...]) +.sp +Test for the existence of any of the named files. +.le +.ls \fB$ifnewer\fR (file, filea) +.in -4 +\fB$ifnewer\fR (file: filea [, fileb, ...]) +.in 4 +.sp +Test if the named file is newer (has been modified more recently) than +any of the named files to the right. The colon syntax may be used for +clarity when comparing one file to many, but a comma will do. +.le +.ls \fB$ifolder\fR (file, filea) +.in -4 +\fB$ifolder\fR (file: filea [, fileb, ...]) +.in 4 +.sp +Test if the named file is older than any of the named files. +.le +.ls \fB$else\fR +.sp +Marks the \fIelse\fR clause of an \fIif\fR statement. The \fIelse-if\fR +construct is implemented as "$else $if", i.e., as a combination of the two +more primitive constructs. +.le +.ls \fB$endif\fR +.sp +Terminates a $if or $if-$else statement. +.le +.ls \fB$end\fR +.sp +Terminates an arbitrary number of $if or $if-$else statements. This is most +useful for terminating a long list of $if-$else clauses, where the alternative +would be a long string of $endif directives. +.le +.ls \fB$exit\fR +Terminate the current program; equivalent to a semicolon, but the latter +is normally used only at the end of the program to match the colon at the +beginning, whereas \fB$exit\fR is used in conditionals. +.le +.le + + +.tp 4 +4.3 Calling Modules + + The following preprocessor directives are available for calling \fImkpkg\fR +modules or altering the normal flow of control. +.ls +.ls \fB$call\fR module[@subdir[/file]] [name=value] [name=value...] +.sp +Call the named mkpkg-file module as a subroutine. In most cases the called +module will be in the current mkpkg-file, but the full module name syntax +permits the module to be in any file of any subdirectory ("./file" references +a different file in the current directory). Arguments may be passed to +the called module using the symbol definition facility; any symbols +defined in this fashion are available to any modules called in turn by +the called module, but the symbols are discarded when the called module returns. +.le +.ls \fB$update\fR module[@subdir[/file]] [name=value] [name=value...] +.sp +Identical to \fB$call\fR except that the named module is understood to +be a library member list. The current value of the symbol XFLAGS is used +if XC is called to compile any files. If the named library does not exist +one will be created (a warning message is issued). +.le +.ls \fB$goto\fR label +.sp +Causes execution to resume at the line following the indicated label. +The syntax of a goto label is identical to that of a mkpkg-file module name, +i.e., a line starting with the given name followed by a colon. +The \fI$goto\fR statement automatically cancels any \fI$if\fR nesting. +.le +.le + + +.tp 4 +4.4 Preprocessor Directives + + The remaining preprocessor directives are described below in alphabetical +order. Additional capability is available via OS escapes, provided the +resultant machine dependence is acceptable. +.ls +.ls \fB$echo\fR message +.sp +Print the given message string on the standard output. The string must be +quoted if it contains any spaces. +.le +.ls \fB$checkout\fR file directory +.sp +Check the named file out of the indicated directory. The checkout operation +makes the file accessible as if it were in the current directory; checkout +is implemented either as a symbolic link or as a physical file copy depending +upon the host system. The referenced directory may be a logical directory, +e.g., "lib$", or a path, e.g, "pkg$images/". Checkout is not disabled by +the "-n" flag. +.le +.ls \fB$checkin\fR file directory +.sp +Check the named file back into the indicated directory. The checkin operation +is implemented either as a remove link or copy and delete depending upon the +host system. Checkin is not disabled by the "-n" flag. +.le +.ls \fB$copy\fR filea fileb +.sp +Make a copy \fIfileb\fR of the existing file \fIfilea\fR. On a UNIX host +the copy operation will preserve the file modify date if the file is a library +(to avoid the "symbol table out of date" syndrome). +.le +.ls \fB$delete\fR file [file ...] +.sp +Delete the named file or files. +.le +.ls \fB$generic\fR [-k] [-p prefix] [-t types] [-o root] files +.sp +Run the generic preprocessor on the named files. The generic preprocessor +is an IRAF bootstrap utility and may not be available on non-UNIX hosts. +.le +.ls \fB$link\fR [switches] file1 file2 ... fileN [-o file.e] +.sp +Call XC with the given argument list to link the indicated files and libraries. +The value of the symbol LFLAGS (default value the null string) is automatically +inserted at the beginning of the command line. This is equivalent to +"!xc $(LFLAGS) ...". +.le +.ls \fB$move\fR file destination +.sp +Move the named file to the indicated directory, or rename the file in the +current directory. +.le +.ls \fB$omake\fR file [dep1] [dep2 ...] +.sp +Compile the named source file if it does not have a corresponding object file +in the current directory, if the object file is older, or if any of the +listed dependency files are newer (or not found). The current value of the +symbol XFLAGS is used if XC is called to compile the file. +.le +.ls \fB$purge\fR directory +.sp +Delete all old versions of all files in the named directory. Nothing is done +if the system does not support multiple file versions. +.le +.ls \fB$special\fR directory : filelist ; +.sp +Add one or more files to the special file list for the host system. This is +a system facility, not intended for use in applications \fImkpkg\fR files. +The special file list is a list of all source files needing special processing +for the local host system. Examples of special files are files which are +optimized in assembler (or some other nonstandard language), or files which +must be compiled in a special way to get around bugs in a host compiler. +The special file list makes it possible to flag arbitrary files for special +processing, without having to modify the standard software distribution. +In the IRAF system, the special file list is defined in the file +"hlib$mkpkg.sf" which is included automatically by "hlib$mkpkg.inc" whenever +\fImkpkg\fR is run. + +The syntax of a \fIfilelist\fR entry is as follows: + + modname source_file mkobj_command + +where \fImodname\fR is the filename of a library module as it appears in a +library module list for the named directory, \fIsource_file\fR is the virtual +pathname of the source file to be used in lieu of the standard portable +source file \fImodname\fR, and \fImkobj_command\fR is the \fImkpkg\fR command +(e.g., $xc or an OS escape) to be executed to compile the named module. +The character "&" appearing in either the source file name or mkobj command +is replaced by \fImodname\fR. If the \fImkobj_command\fR is omitted the +specified source file will be compiled with $XC using the current value of +XFLAGS. +.le +.ls \fB$xc\fR [switches] file1 file2 ... fileN +.sp +Call the XC compiler to compile the named files. Note that the value of +the symbol XFLAGS is \fInot\fR used when XC is explicitly called in this +fashion (XFLAGS is used by \fB$update\fR and \fB$omake\fR). +.le +.ls \fB$debug\fR [on|off] +.sp +Turn debug mode on or off. If no argument is supplied debug mode is turned +on. Turning on debug mode automatically enables verbose mode. +.le +.ls \fB$verbose\fR [on|off] +.sp +Turn verbose mode on or off. If no argument is supplied verbose mode is turned +on. +.le +.le + + +.tp 4 +5. Error Recovery + + \fBMkpkg\fR is implemented in such a way that it is restartable. If a mkpkg +operation terminates prematurely for some reason, e.g., because of a compile +error, execution error (such as cannot find the mkpkgfile in a subdirectory), +interrupt, etc., then the mkpkg command can be repeated after correcting +the error, without repeating the operations already completed. If \fBmkpkg\fR +is interrupted it may leave checked out files, objects compiled but not yet +updated in a library, etc. lying about, but this is harmless and the +intermediate files will be cleaned up when the errors have been corrected +and the run successfully completes. + +.ih +EXAMPLES +Update the current package. + + cl> mkpkg + +Update the package library but do not relink. + + cl> mkpkg libpkg.a + +Make a listing of the package. + + cl> mkpkg listing + + +.ks +.nf +Sample mkpkg-file for the above commands: + + + # Make my package. + + $call relink + $exit + + relink: + $update libpkg.a + $omake x_mypkg.x + $link x_mypkg.o -lxtools + ; + + libpkg.a: + task1.x pkg.h + task2.x + filea.x pkg.com pkg.h <fset.h> + fileb.x pkg.com + ; + + listing: + !pr task1.x task2.x file[ab].x | vpr -Pvup + ; +.fi +.ke +.ih +SEE ALSO +xc, generic, softools package |