Provided by: iraf-dev_2.17.1-3_amd64 bug

NAME

       mkpkg - make or update an IRAF package or library

SYNOPSIS

       mkpkg [options] [ module ...  ] [ name=value ...  ]

ARGUMENTS

       -d[ddd]
              Debug  mode.   Print  detailed  messages describing what mkpkg 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.

       -f file
              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 mkpkg.

       -i     Ignore errors. Execution continues even if an error occurs.

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

       -p pkgname
              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 must be specified when doing software development in  an  external
              or layered package.

       -v     Verbose  mode.   A message is printed whenever a file is touched.  Recommended when
              running large mkpkg jobs in batch mode.

       module 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
              mkpkg macro preprocessor directive  at  the  beginning  of  the  file  specifies  a
              different default action.

       name=value [name=value ...]
              Enter  the  named  symbol/value  pair  into  the  symbol  table  of the mkpkg macro
              preprocessor.  The symbols XFLAGS (for the XC compiler) and LFLAGS (for the linker)
              are predefined but may be redefined on the command line.  Case is ignored in symbol
              names for portability reasons.

DESCRIPTION

       The mkpkg utility is used to make or update IRAF packages or libraries.  mkpkg 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).  mkpkg is upwards compatible with the  old  mklib
       utility.

1. Introduction

       Mkpkg 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 mkpkg to update entire directory trees, or to  enter  the  hierarchy  of  mkpkg
       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  mkpkg  will  update
       only  the system libraries, and in the "iraf$sys/fio" directory mkpkg will update only the
       FIO portion of the system library "libsys.a".

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

2. Lexical Conventions

       The  lexical  conventions  employed in mkpkg 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.

               .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

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

               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]

       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.

3. Maintaining Libraries with MKPKG

       Libraries are described by a member list module in the "mkpkg"  file.   The  syntax  of  a
       library  member list module is shown below.  Note that the mkpkg 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".

               libname.a:
                   member1         dep1 dep2 ... depN
                   member2         dep1 dep2 ... depN
                     ...
                   memberN         dep1 dep2 ... depN
                   ;

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

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

       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
       mkpkg  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  mkpkg  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 $update operator.

               libpkg.a:
                   @(i2)
                   alpha.x
                   beta.x
                   zeta.f
                   ;
               i2:
                   $set    XFLAGS = "-cO -i2"
                   gamma.f
                   delta.f
                   ;

       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 $set statement shown.

4. The MKPKG Macro Preprocessor

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

4.1. Symbol Replacement

       Symbol substitution in the mkpkg 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 mkpkg command line, in  the  argument  list  to  a  $call  or
       $update  directive (see below), in an include file referenced with the $include directive,
       or in a $set 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 mkpkg 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  dev$graphcap file on the mkpkg
       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 "$(@file)".   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.

               $echo $(dev)graphcap
               !xc $(XFLAGS) filea.x fileb.x

       Symbols are most commonly defined locally with the $set directive.  The $include directive
       is useful for sharing symbols amongst different modules,  or  for  isolating  any  machine
       dependent   definitions   in  a  separate  file.   The  IRAF  mkpkg  system  include  file
       hlib$mkpkg.inc is automatically included whenever mkpkg is run.

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

       $include filename
              Read commands (e.g., $set 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.

              The use of the $set directive is  illustrated  in  the  example  below.   Note  the
              doubling  of  the preprocessor metacharacter 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.

                      $set GFLAGS = "-k -t silrdx -p ak/"
                      $set GEN    = "$generic $$(GFLAGS)"

                      ifolder (amulr.x, amul.x) $(GEN) amul.x $endif

4.2 Conditional Execution

       Conditional  control  flow  is  implemented  by  the $if 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.

       $ifdef (symbol [, symbol, ...])

              Test for the existence of one of the named symbols.

       $ifeq (symbol, value [, value, ...])

              Test if the value of the named symbol matches one of the listed value strings.

       $iferr

              Test for an error return from the last directive executed  which  touched  a  file.
              This has only effect if mkpkg is invoked with the -i option so that it doesn't exit
              on the first error.

       $iffile (file [, file, ...])

              Test for the existence of any of the named files.

       $ifnewer (file, filea)
       $ifnewer (file: filea [, fileb, ...])

              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.

       $ifolder (file, filea)
       $ifolder (file: filea [, fileb, ...])

              Test if the named file is older than any of the named files.

       $else

              Marks the else clause of an if statement.  The else-if construct is implemented  as
              "$else $if", i.e., as a combination of the two more primitive constructs.

       $endif

              Terminates a $if or $if-$else statement.

       $end

              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.

       $exit  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 $exit is used in conditionals.

4.3 Calling Modules

       The  following preprocessor directives are available for calling mkpkg modules or altering
       the normal flow of control.

       $call module[@subdir[/file]] [name=value ...]

              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.

       $update module[@subdir[/file]] [name=value ...]

              Identical to $call 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).

       $goto

              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  $goto  statement
              automatically cancels any $if nesting.

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.

       $echo message

              Print the given message string on the standard output.  The string must  be  quoted
              if it contains any spaces.

       $checkout file directory

              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.

       $checkin file directory

              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.

       $copy filea fileb

              Make  a  copy  fileb of the existing file filea.  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).

       $delete file [file ...]

              Delete the named file or files.

       $generic [-k] [-p prefix] [-t types] [-o root] files

              Run  the  generic  preprocessor on the named files.  The generic preprocessor is an
              IRAF bootstrap utility.

       $xyacc [options] file

              Run the xyacc parser generator on the named files.  The yacc parser generator is an
              IRAF bootstrap utility.

       $link [switches] file1 file2 ... fileN [-o file.e]

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

       $move file destination

              Move the named file to the indicated directory, or rename the file in  the  current
              directory.

       $omake file [dep1] [dep2 ...]

              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.

       $purge directory

              Delete all old versions of all files in the named directory.  Nothing  is  done  if
              the system does not support multiple file versions.

       $special directory : filelist ;

              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  mkpkg  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 mkpkg is run.

              The syntax of a filelist entry is as follows:

                      modname source_file mkobj_command

              where modname is the filename of a library module as it appears in a library module
              list  for  the  named  directory, source_file is the virtual pathname of the source
              file to be used  in  lieu  of  the  standard  portable  source  file  modname,  and
              mkobj_command  is  the  mkpkg 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 modname.  If the mkobj_command is omitted the
              specified source file will be compiled with $XC using the current value of XFLAGS.

       $xc [switches] file1 file2 ... fileN

              Call the XC compiler to compile the named files.  Note that the value of the symbol
              XFLAGS  is not used when XC is explicitly called in this fashion (XFLAGS is used by
              $update and $omake).

       $debug [on|off]

              Turn debug mode on or off.  If no argument is supplied debug  mode  is  turned  on.
              Turning on debug mode automatically enables verbose mode.

       $verbose [on|off]

              Turn verbose mode on or off.  If no argument is supplied verbose mode is turned on.

5. Error Recovery

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

       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

              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
                          ;

SEE ALSO

       generic(1), xc(1).

       There is also information in the README.softools in the IRAF documentation directory.

AUTHOR

       This manual page was taken from the IRAF mkpkg.hlp help file.