guide.doc

speech signal process tools

       As mentioned, since release 4.1, the root of the ESPS  directory  tree
       does  not have to be accessible as /usr/esps; all that is necessary is
       to make sure that the Unix environment variable ESPS_BASE contains the
       root  location,  whatever  it  may  be.   Programs that need to access
       directories in the tree use the environment find  the  root.   Further
       provisions have been made to allow customizing of the search paths for
       certain types of files.   For  example,  when  read_params(3-ESPS)  is
       searching  for a parameter file given to a program with the -P option,
       its default behavior is to search first in the current working  direc-
       tory and then in the directory $ESPS_BASE/lib/params in the ESPS tree.
       However, if the environment variable  ESPS_PARAMS_PATH  is  set,  this
       default search path (".:$ESPS_BASE/lib/params") is overridden, and the
       value of ESPS_PARAMS_PATH is used instead.  The key to this  flexibil-
       ity  is  the ESPS utility function find_esps_file(3-ESPS) and a set of
       macros defined in $ESPS_BASE/include/esps/epaths.h.  For  example,  if
       param is a string containing an argument to -P, the C statement

           full_path = FIND_ESPS_PARAM_FILE((char *) NULL, param);

       suffices to get a full path name  to  the  right  parameter  file  and
       assign  it  to the string variable full_path.  The macro invocation on
       the right-hand side expands to

           find_esps_file((char *) NULL, param,
                           ".:$ESPS_BASE/lib/params", "ESPS_PARAMS_PATH")


       Version 3.6                      ERL                           1/22/93







       ETM-S-86-14                                                     page 7


       and  the  function  does  the  rest.   See   the   manual   page   for
       find_esps_file(3-ESPS)    for    more    details,    and    look    in
       $ESPS_BASE/include/esps/epaths.h for the full set of default paths and
       environment variables.

       4 .  ESPS Compilation Environment

       The ESPS environment is a set of variables  that  specify  compilation
       options and the locations of key esps directories.  To aid programmers
       who are working on ESPS  programs,  we  provide  scripts  ecc(1-ESPS),
       elint(1-ESPS),  and  emake(1-ESPS).  The first two of these call cc(1)
       and lint(1) with flags identifying the location of ESPS include  files
       and  libraries.   The  emake script calls make(1) with flags that pass
       appropriate environment variables.  The script has the following form,
       though  this is a greatly abbreviated verson; the variables are listed
       in full further down.

             #! /bin/sh
             exec make \
             BINDIR=`get_esps_base`/bin \
             LINT="lint -b -c " \
             LINTFLAGS=" -I`get_esps_base`/include -DSUN4" \
             MANMOD=0644 \
             PARAMDIR=`get_esps_base`/lib/params \
             PROGCFLAGS=" -DSCCS -I`get_esps_base`/include -DSUN4 -DOS4" \
             PROGMOD=0755 \
             SINC=`get_esps_base`/include/esps \
             STRIP="strip" \
             LINTLIB=`get_esps_base`/lib/llib-lespsg.ln \
             $*


       Note that directory names in the ESPS tree are given in terms  of  the
       value  returned  by a function get_esps_base(1-ESPS); this returns the
       value of the environment variable ESPS_BASE, if defined, and otherwise
       returns "/usr/esps" as a default.

       Users of emake(1-ESPS) should start with an ESPS makefile  that  looks
       like this:

         # This material contains unpublished, proprietary software of
         # Entropic Research Laboratory, Inc. Any reproduction, distribution,
         # or publication of this work must be authorized in writing by Entropic
         # Research Laboratory, Inc., and must bear the notice:
         #
         #    "Copyright (c) 1990-1991  Entropic Research Laboratory, Inc.
         #                   All rights reserved"
         #
         # The copyright notice above does not evidence any actual or intended
         # publication of this source code.
         #
         # @(#)guide.vme 3.6 1/22/93 ERL
         #


       Version 3.6                      ERL                           1/22/93







       ETM-S-86-14                                                     page 8


         # Makefile for: foo
         #
         # Written by:
         # Checked by:
         # Revised by:

         CFLAGS = -g $(PROGCFLAGS)

         OBJS = foo.o
         SRCS = foo.c
         PROGNAME = foo
         MANNAME = foo.1
         DEFPARAM = Pfoo


         $(PROGNAME): $(SPSLIB) $(OBJS)
                 cc  $(CFLAGS) $(OBJS) $(SPSLIB) -lm -o $(PROGNAME)

         $(OBJS): $(SINC)/esps.h

         install: $(PROGNAME)
                 $(STRIP) $(PROGNAME)
                 -mv -f $(BINDIR)/$(PROGNAME) $(OLDBIN)/$(PROGNAME)
                 -chmod $(PROGMOD) $(OLDBIN)/$(PROGNAME)
                 mv -f $(PROGNAME) $(BINDIR)/$(PROGNAME)
                 chmod $(PROGMOD) $(BINDIR)/$(PROGNAME)
                 -diffmk $(MANDIR)/man1/$(MANNAME) $(MANNAME) man.diff
                 @echo diffmked man page left in man.diff
                 -rm $(MANDIR)/man1/$(MANNAME)
                 cp $(MANNAME) $(MANDIR)/man1/$(MANNAME)
                 chmod $(MANMOD) $(MANDIR)/man1/$(MANNAME)
         # install the default parameter file
                 -rm -f $(PARAMDIR)/$(DEFPARAM)
                 cp $(DEFPARAM) $(PARAMDIR)/$(DEFPARAM)
                 chmod $(LIBMOD) $(PARAMDIR)/$(DEFPARAM)

         clean:
                 -rm -f $(OBJS) $(PROGNAME) core

         lint:   $(SRCS)
                 $(LINT) $(LINTFLAGS) $(SRCS) $(LINTLIB) > lint

         test:   $(PROGNAME)
                 sh $(PROGNAME).test


       An  example  makefile  may  be  found  on  line;   the   location   is
       <$ESPS_BASE/lib/makefile.ex>.

       All of the macros used are passed in as environment  variables  or  by
       emake(1-ESPS),  except  for  CFLAGS, which is passed in as PROGCFLAGS.
       This is done so that the programmer can add additional  options,  such
       as -g or -O.


       Version 3.6                      ERL                           1/22/93







       ETM-S-86-14                                                     page 9


       Here is a full list of the esps compilation environment (most of these
       are not usually dealt with explicitly by users):

         ADDEV          The pathname of the analog-to-digital converter device.
         ADTYPE         The name of the ADDEV.  (See equipment codes in
                        <esps/header.h>.)
         BINDIR         The directory for esps user level executables.
         CC             The C compiler command (e.g. cc).
         CLKDEV         The data acquisition system clock device.
         DADEV          The digital-to-analog converter device.
         DEFAULT_PAGER  The system wide default pager program (e.g. more).
         EHDRLIB        Header library for linking with ESPS functions.
         EQN            Filter for typesetting equations (e.g. eqn).
         EXVLIB         Library of ESPS functions that use the XView toolkit.
         FLOAT          The cc option switch for the floating point type.
         HMOD           File access mode for header library functions.
         LIBCFLAGS      The CFLAGS for use with the library C files.
         LIBDIR         The directory for the esps object library and lint library.
         LIBFFLAGS      Flags for compiling library functions in Fortran.
                        Currently unused.
         LIBMOD         The file access mode of the items that go into the library.
         LIBNAME        Name of the esps library binary.  Used by library makefile.
         LINK           Command to link binaries (e.g., "ln -s").
         LINT           The lint command to use (e.g. "lint -b -c").
         LINTFILE       Name of the lint library source file.  Used by echeck.
         LINTFLAGS      The flags to use with lint
         LINTLIB        The name of the lint library
         LLIBNAME       Name of the lint library binary.
         MACH           The code for the machine type (M5600, SUN3, etc)
         MANDIR         The parent of the man page directory (e.g. $ESPS_BASE/man)
         MANMOD         The access mode of the man pages
         MAXAD          The max value from this A/D
         MAXDA          The max value from this D/A
         MCD            Command for displaying GPS output from plot programs
                        (e.g. xmcd)
         MINAD          The min value from this A/D.
         MINDA          The min value from this D/A.
         MKLINTLIB      The command to make the lint libary. Used only by the
                        library makefile.
         OLDBIN         The place for old versions of esps binaries
         OLIBCFLAGS     ``Other'' CFLAGS, used for a few library functions.
         PARAMDIR       Directory of default parameter files (e.g.
                        $ESPS_BASE/lib/params).
         PLOTCOMMAND    Command for plotting Tektronix-style output from plot
                        programs.  (e.g. esps_plot)
         PLOTDIR        The directory for plotting programs that are called by
                        cover programs.
         PROGCFLAGS     The CFLAGS for use in compiling C programs.  Contains a
                        -I option with the correct path to the esps include
                        files.
         PROGFFLAGS     Flags for compiling Fortran programs.  Currently unused.
         PROGMOD        The access mode of esps user programs.
         RANLIB         Command for converting a library to a form that loads more


       Version 3.6                      ERL                           1/22/93







       ETM-S-86-14                                                    page 10


                        rapidly.  (e.g. ranlib)
         SINC           The directory of esps include files.
         SPOOL_CMD      Command for spooling files to a printer (e.g. ipr).
         SPSDIR         The parent esps install directory.
         SPSLIB         The full paths of all esps libraries.  Used for programs
                        that require an ESPS license to run (cf. WSPSLIB).
         STRIP          equal to "-strip" if binaries are to be stripped. see
                        strip(1).
         VTROFF         The name of the program to typeset man pages.
         WAVESDIR       Files related to the waves+ program.
         WHDRLIB        Header library for linking with waves+-related programs.
         WINDOWS        Compiler option selecting a window system.  (e.g. -DXWIN)
         WINLIBS        Loader option selecting window-system libraries.
                        (e.g. -lX11)
         WSPSLIB        Used instead of SPSLIB for programs that will run under
                        either a waves or an ESPS license.
         XVIEW_B_OPT    C compiler option that specifies whether the XView object
                        libraries are loaded statically (non-shared) or dynamically
                        (shared).
         XVIEW_INC      Directory of include files for programs that use XView.
         XVIEW_LIB      Loader options selecting XView libraries.
         XWIN           Use X windows?  (e.g. YES or NO)


       SPSLIB normally contains names of three libraries:   the  library  for
       XView-dependent  ESPS  functions, the general ESPS library for header-
       related functions, and the general library for other  functions  (e.g.
       "$ESPS_BASE/lib/libexv.a                      $ESPS_BASE/lib/libhdre.a
       $ESPS_BASE/lib/libespsg.a").  WSPSLIB differs in having "libhdrw.a" in
       place of "libhdre.a".

       5 .  Manual Pages

       Every ESPS program must have a UNIX-style manual page.  In most cases,
       this should be written and reviewed before the program itself is writ-
       ten.  ESPS manual pages have several sections  in  addition  to  those
       that are conventional for UNIX, namely the following:

              ESPS PARAMETERS
              ESPS COMMON
              ESPS HEADERS
              FUTURE CHANGES

       The "ESPS PARAMETERS" section lists the parameters that are read  from
       the  parameter  or  common  file  and  gives their types.  The section
       should explain how the program uses each of these parameters.

       The "ESPS COMMON" section describes how the ESPS Common file  is  pro-
       cessed  (e.g.,  whether  the filename in Common is required to match a
       particluar file name), and what items, if any, are written to the Com-
       mon file.




       Version 3.6                      ERL                           1/22/93







       ETM-S-86-14                                                    page 11


       The "ESPS HEADERS" section lists the generic header  items  and  other
       header  items  that  are  read by the program, and it explains how the
       program depends on them.  This section also  lists  the  header  items
       that are written by the program.

       The "FUTURE CHANGES" section is intended to record ideas for enhancing
       the  program.   This  section  should be included even when the manual
       page is written before the program, since its contents may affect  the
       program structure.

       6 .  Command Line Format and Pipelines

       The command line for any ESPS program will be

           prog options input-files output-files

       Options, if present, will be of the standard  UNIX  form  (  -x  ,  -x
        text, or -xtext ).

       By default, the parameter file for the program is the file "params" in
       the current directory.  All ESPS programs that process parameters will
       recognize the option

           -P paramfile,

       which can specify an alternative parameter file name.

       If the output of the program is ASCII text then the default output  is
       standard  output.   This can be redirected by the user, if desired, by
       using the standard UNIX shell facilities.    If the output of the pro-
       gram  is  binary  data,  then  an output file must be specified.  If a
       minus sign is given, then standard output is used.  The intent here is
       to  reduce  the chance that a user will accidently send binary data to
       his terminal.  Any source file name may be replaced by a  minus  sign,
       meaning that this source is read from the standard input (if a program
       takes multiple source files, only one may be read from standard input,
       however).  Standard  input  or  standard  output  are  never to be the
       default if a binary data file is involved.

       Where reasonable, pipelines should be allowed.  If a program  performs
       random  I/O  on  its  input,  that fact should be included in the user
       documentation. If a program reads from a pipe, it  writes  the  string
       "<stdin>"  as  the  source  file name in the output header.  Note that
       programs that read ESPS files from pipes can not depend on the  header
       item common.ndrec---see ESPS(5-ESPS).

       Programs that perform plots or dumps, or that compute statistics, have
       different  syntax.  For one thing, they do not accept parameter files.
       They are invoked by lines of the form

           prog options src1 [src2 ...]

       The output should go to the standard output.   Where  reasonable,  the


       Version 3.6                      ERL                           1/22/93