EXPLODE(1)                                                          EXPLODE(1)



NAME
       explode - unpack components from aggregated source archives

SYNOPSIS
       explode  [-cfinv]  [-d  delimiter]  [-e  extender] [-I dir] [-o prefix]
       [-R remote] [-u unpack] [files]
       explode [-tv]  [-d  delimiter]  [-e  extender]  [-I  dir]  [-o  prefix]
       [-R remote] [-u unpack] [files]
       explode [-finv] [-e extender] [-I dir] [-o prefix] [-R remote] [files]
       explode -h
       explode -H
       explode -T
       explode -V
       explode  -s  [-finSv]  [-e  extender]  [-I dir] [-o prefix] [-R remote]
       [files]


DESCRIPTION
       Explode breaks a source file  into  separate  compilation  units.   The
       source text should contain control directives of the form
            delimiterdirective argument
       all of which must begin in column one of a source line.

       A  MICE  "library" or family is the least specific implementation of an
       algorithm.  Unlike a run-time configured routine (like qsort(3)) a MICE
       family  is  configured  via  compile time macros: thus no efficiency or
       functionality is lost due to a "bad fit".

       MICE families come packaged in two files: a large  source  file  and  a
       small  header  file.   The  C source file, for example, may be compiled
       with a -DTEST option to provide a simple test program.  The header file
       is  intended  to  provide all the function prototypes needed to use the
       family.  Before the library can be configured for a new application the
       user  should  run  the  C source through explode.  Of course, any addi-
       tional make(1) descriptions, manual pages, and/or  HTML  documents  for
       the library may be kept as well.

       The  Explode  directive opens a new output stream according to the fol-
       lowing name (eg. "/*@Explode name@*/" for C text).  The name is assumed
       to  end  at  either the first white-space character or the first occur-
       rence of the last character in delimiter.  The name is prefixed by pre-
       fix  and  extended  by  extender;  the  resulting  string  is passed to
       fopen(3) as a file name.

       The Append directive opens a new output stream according to the follow-
       ing  name.  The name is treated as if it were for an Explode directive,
       but the file is opened for append and no header is prefixed to it.

       The Header directive instructs explode to begin saving  a  header  that
       should be copied to the beginning of all the output files.  This direc-
       tive has no argument (yet).  To remove this  from  the  output  see  -c
       below.

       The  Remove  directive  diverts  text  to the null device until another
       directive opens a new destination.

       The Message directive diverts text to the invokers  tty  until  another
       directive opens a new destination.

       The  Insert directive copies its argument to the current output stream.
       The first non-white character of the argument is taken to be  a  delim-
       iter that marks the end of the string.

       The Shell directive copies the output of the given sh(1) command to the
       current output stream.  The shell command is enclosed  in  quotes  (any
       non-white character).

OPTIONS
       The  environment  variable $EXPLODE is read for options before the com-
       mand-line option are processed.

       -c
              Under this flag none of  the  exploded  modules  will  have  the
              Header  section  included.   This  is useful when they are to be
              subsequently textually included in another file (via  cpp(1)  or
              the like).

       -d delimiter
              Use  the given delimiter rather than the default for the current
              extender. Delimiters should be short strings.  The  table  below
              gives some of the default delimiters:

             extension   language   default delimiter
              c or h        C              /*@
                 k          K              /*@
                 f       FORTRAN           c@
                 p        Pascal           (*@
                sh          sh             #@
                csh        csh             #@

       -e extender
              In an Explode directive, the extender will be added to the base-
              name.  By default it is the extender of the source file, or ".c"
              if no extender can be found.

       -f
              Normally  explode  will  not  overwrite  existing files: if this
              option is given it will.

       -h
              Output a only usage summary.

       -H
              Output only a short file format reminder.

       -i
              Confirm any file over-write operations, like rm(1).

       -I dir
              A colon separated directory path to  search  for  source  files.
              The default repository is displayed under -V.

       -n
              Print  what  would  be  done but don't build files.  This option
              implies the -v option.

       -o prefix
              In an Explode directive the prefix will  be  placed  before  the
              basename.  By default it is the basename of the file being read.
              a prefix of dash ("-") directs the output to stdout.

       -R remote[:explmux]
              Consult a tcpmux(8l) service on remote  to  find  the  aggregate
              file.   Operate  on  the stream locally.  The default explmux is
              "explmux", and it usually not  changed  by  local  site  policy.
              This  option  may  be  disabled  at  compile  time, if the local
              machine can't support getaddrinfo(3).  See explmux(7l).

       -s
              Output only the source module located (do not  explode  it  into
              the parts).  This option is often used to copy source modules to
              a temporary directory.

       -S
              Just display the path to the source file we located.

       -t
              Output only the table of contents  from  each  source  file,  as
              tar(1) does for any archive.

       -T
              Only list the recognized file extenders.

       -u unpack
              Cause  explode  to unpack only the listed files. Unpack may be a
              list of names separated by commas.  This option my  be  repeated
              to concatenate the lists.

       -v
              Output a running synopsis of explode's actions.

       -V
              Output only explode's version information.

EXAMPLES
       explode -o /tmp/foo -e .c kevin
              To  unpack  the  file "kevin" to /tmp/foobasename.c which should
              create /tmp/fooone.c and /tmp/footwo.c.

       explode -o /tmp/avl -u ins -u del -u init avl.c
              Only unpack the insert, delete and init routines  from  the  AVL
              source file.

       explode -t mk.c
              Extract  the  catalog of available components from the mk.c mod-
              ule.

       explode -o - -u utemp mk.c |${PAGER:-more}
              Output the unix domain socket code  from  the  mktemp  emulation
              library to stdout, send that output to a pager.

       explode -T |${PAGER:-more}
              Output  the  list  of  all  the default markup expected for each
              extender.

       explode -s avl.c
              Copy the Adelson-Velskii Landis height-balanced tree  module  to
              the current directory.

       cp -i 'explode -sS avl.c' .
              Same as above, but use cp(1) to avoid an accidental overwrite of
              any local copy.

       explode -s -R explode.example.com avl.c
              Download the same module from the local explmux(7l) service.

BUGS
       There is no inverse of the -c option: that is there is no (good) way to
       just get the Header section of the archive.  Using diff(1) to get it is
       an unnecessary hack: you almost never need the header without at  least
       one function.

AUTHOR
       KS Braunsdorf, NonPlayer Character Guild
       mkcmd and no-spam on ksb.npcguild.org

       This  is  a  modification  of the original Purdue code, by the original
       author.  Since Purdue doesn't distribute explode anymore --  you  might
       have to live with this version.

SEE ALSO
       explode(5l), explmux(7l), make(1), cc(1), sh(1), mkcmd(1l), basename(1)



                                     LOCAL                          EXPLODE(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLES | BUGS | AUTHOR | SEE ALSO