guide.vme

speech signal process tools

.lo
.de SM          \"macro to shrink left margin
.br
.nr $i \\n($i+\\$1i
..
.de RM          \"macro to restore original left margin
.br
.nr $i 0
..
.AU "Joe Buck, Alan Parker, and John Shore"
.RB "John Shore (with help from Rod Johnson)"
.SJ "Entropic Signal Processing System (ESPS) Programming Guidelines"
.TM ETM-S-86-14 1.5 6/18/87
.*R
ETM-S-86-13:rap/jtb, Data Files in the Entropic Signal Processing System (ESPS)
.*R
ETM-S-86-12:jtb, Parameter and Common Files in the Entropic Signal Processing System (ESPS)
.*R
ETM-S-86-25:rap, Guidelines for Programming with FEA Files 
.*R
ESPS Users Manual 
.*R
J. Shore and R. Parker, Introduction to the Entropic Signal Processing System (ESPS)
.sh 1 Introduction
.lp
This document describes various programming conventions and guidelines
for the Entropic Signal Processing System (ESPS).  
.(f
\(co copyright 1987 Entropic Speech, Inc.; All rights reserved.  
.)f
Readers of this document should also read [1-3.  A general
familiarity with the reference manual [4] is also assumed.  For a
general introduction to ESPS, see [5].
.lp
This document describes the command line format of ESPS programs,
internal program structure, programming conventions, and the
organization of the ESPS directory tree.  
.sh 1 "Directory Structure"
.lp
The ESPS distribution comprises a a directory tree with the suggested
default root /usr/esps.  Many of the installed locations for the top
level of this tree can be specified independently by the local system
manager using facilities provided by the ESPS installation program.
For purposes of this memorandum, however, we assume that the default
locations are used with a root of /usr/esps.  Here is a sketch of the
ESPS directory tree:
.(b
.ft CW
.nf
                |-bin
                |-bin.local
                |-doc
                |
                |               |-bin
                |               |-doc
                |               |-h
                |               |
                |               |-lib-----------|-filt
                |               |               |-testdata
                |               |
                |               |               |-man1
                |-general-------|-man-----------|-man3
                |               |               |-man5
                |               |
                |               |               |-lib
                |               |               |-misc
                |               |-src-----------|-prog1
                |                               |-prog2
                |                               |-prog...
                |                               |-progN
                |
                |-include-------|-esps
                |
                |-include.local-|-esps
                |
|-esps----------|-lib-----------|-maclib
                |
                |               |-bin
                |               |-doc
                |               |-h
                |               |-lib
                |               |
                |               |               |-man1
                |               |-man-----------|-man3
                |-local---------|               |-man5
                |               |
                |               |               |-lib
                |               |               |-misc
                |               |-src-----------|-prog1
                |                               |-prog2
                |                               |-prog...
                |                               |-progN
                |
                |               |-cat1
                |               |-cat3
                |-man-----------|-cat5
                                |-man1
                                |-man3
                                |-man5
.fi
.)b
.ft LR
.lp
The following are brief descriptions of the main ESPS directories
(the root path /usr/esps/ is not included):
.ip bin: 
Executable programs in the general release.  This directory should be
added to ESPS users' paths.
.ip bin.local:
Executable programs local to a particular system; these would be
programs that are not part of the general ESPS release but are
created locally.  
.ip doc:
ESPS documents.
.ip include:
Include files for general ESPS source programs.  
.ip include.local:
Include files for local ESPS source programs.  
.ip lib:
The location of public ESPS files.  The install script moves things
to this directory.  This is the default location for the ESPS
libraries.  The maclib subdirectory contains mock-lisp files for
emacs support of ESPS programming.  
.ip man:
The root of a tree containing the on-line ESPS manual pages (i.e., this is
where \fIeman\fP(1\-\s-1ESPS\s+1) looks).  Subdirectories include: 
.ip man/man1:
Manual pages for user-level programs.  
.ip man/man3:
Manual pages for library routines.
.ip man/man5:
Manual pages for file formats.
.lp
There are also associated man/cat? directories for the 
formatted manual pages (created by \fIeman\fP).
.ip general:
The root of a tree containing the distributed binaries and sources.  
.ip local:
The root of a tree containing local sources.  
.lp
The general and local subtrees have the same structure.  Here, we
just describe general.
.ip general/src:
Source directory.  This directory will have subdirectories for all
major programs.  The source code stored here will be \fISCCS get\fR
versions.  The \fISCCS\fR directories will be maintained elsewhere.
Files in this directory should be read-only.  Source for simple (one
module) ESPS programs will be kept in general/src/misc.  Source 
for library routines will be in general/src/lib.  
.ip general/h:
Include files.  The install script moves these to
include.  
.ip general/src/test:
Programs written to test ESPS features (e.g., to test the header
programs) will be stored here.
.ip general/bin:
Location of distributed binaries.  The install script will move these
to bin.  
.ip general/doc:
Documents, such as this one, describing features of the ESPS as a
whole.  Both source files (for nroff/troff) and ASCII document files
are be stored in this directory.
.ip general/lib:
The root of a tree containing public ESPS files.  Subdirectories 
include:
.ip general/lib/filt:
Filter files (FILT files) of general utility.
.ip general/lib/testdata:
Fixed reference data for program testing.  
.ip general/man:
The root of a tree containing the distributed ESPS manual pages. The 
install script will move these to man.  
.sh 1 "ESPS Compilation Environment"
.lp
The ESPS install scripts (default locations /usr/esps/general/install and
/usr/esps/local/install) define a set of environment variables that
specify the location of key esps directories and compilation
options.  These may be changed by the person who runs the install
scripts.  To aid programmers who are working on general ESPS programs, 
the install script creates 
.i ecc
(1\-\s-1ESPS\s+1)
.i elint
(1\-\s-1ESPS\s+1)
and 
.i emake
(1\-\s-1ESPS\s+1) as well as versions of these for programmers
working on local ESPS programs.  The first two of these call
.i cc
(1) and
.i lint
(1) with appropriate flags identifying the location of ESPS include
files and libraries.  The 
.i emake
script calls 
.i make
(1) with flags that pass the appropriate environment variables.  
.lp
Users of 
.i emake
(1\-\s-1ESPS\s+1)
should start with an ESPS makefile that looks like this:
.SM .2i
.lp
.nf
.ft CW
#  This material contains proprietary software of Entropic Speech, Inc.   
#  Any reproduction, distribution, or publication without the the prior	   
#  written permission of Entropic Speech, Inc. is strictly prohibited.
#  Any public distribution of copies of this work authorized in writing by
#  Entropic Speech, Inc. must bear the notice			
# 								
#      "Copyright (c) 1987 Entropic Speech, Inc.; All rights reserved"
# 				
#  makefile for atofilt @(#)guide.vme	1.5 6/18/87 ESI


CFLAGS =  $(PROGCFLAGS)


OBJS =	    foo.o beta.o gamma.o alpha.o

SRCS =	    foo.c beta.c gamma.c alpha.c

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

foo.o:	$(SINC)/esps.h $(SINC)/filt.h
beta.o:   $(SINC)/esps.h $(SINC)/anafea.h $(SINC)/fea.h $(SINC)/sd.h
gamma.o:  $(SINC)/esps.h $(SINC)/anafea.h
alpha.o:  $(SINC)/esps.h

install: foo
	-strip foo
	-mv $(BINDIR)/foo $(OLDBIN)/foo
	mv -f foo $(BINDIR)/foo
	chmod $(PROGMOD) $(BINDIR)/foo
	-diffmk $(MANDIR)/man1/foo.1 foo.1 man.diff
	@echo diffmked man page left in man.diff
	cp foo.1 $(MANDIR)/man1/foo.1
	chmod 0640 $(MANDIR)/man1/foo.1

clean:	
	-rm -f $(OBJS) foo 
	
lint:	foo.c
	$(LINT) $(LINTFLAGS) $(SRCS) $(LINTLIB) -lm > lint


.fi
.RM
.ft LR
.lp
All of the macros used are passed in as environment variables by the
install script or by
.i emake
(1\-\s-1ESPS\s+1), 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.
.lp
Here is a full list of the esps compilation environment (most of these
are not usually dealt with explicitly by users):
.SM .25i
.lp
.nf
.ta 1.5i

BINDIR		The directory for esps user level executables
LIBCFLAGS 	The CFLAGS for use with the library C files.
LIBDIR		The directory for the esps object library and lint library
LIBMOD		The file access mode of the items that go into the library
LINT		The lint command to use (eg. "att lint")
LINTFLAGS	The flags to use with lint
LINTLIB		The name of the lint library
LLIBNAME	The name of the lint library source
MANDIR		The parent of the man page directory (eg /usr/esps/man)
MANMOD		The access mode of the man pages
OLDBIN		The place for old versions of esps binaries
PLOTDIR		The directory for plotting programs that are called by
		cover programs
PROGCFLAGS	The CFLAGS for use with the library C files.  Contains a
		-I option with the correct path to the esps include
		files.
PROGMOD		The access mode of esps user programs
SINC		The directory of esps include files (general)
SINCL		The directory of esps include files (local)
SPSLIB		The full path of all esps libraries  
SPSDIR		The parent esps install directory

.RM
.fi
.lp
SPSLIB might contain one or two library names.  For use under the
general environment (\fIecc\fR or \fIemake\fR) it will contain only
one; the general ESPS library name (eg.  /usr/esps/lib/libespsg.a).
For use under the local ESPS environment it will contain both the
general and the local library names (eg.  "/usr/esps/lib/libespsl.a
/usr/esps/lib/libespsg.a").  The scripts 
.i ecc,
.i elint,
and
.i emake
and emake use the general environment.  The
scripts 
.i lecc,
.i lelint,
and
.i lemake
use both the general and local
environment.
.sh 1 "Manual Pages"
.lp
All ESPS programs must have a \s-1UNIX\s+1-style manual page.  In most cases, 
this should be written and reviewed before the program itself is
written.  ESPS manual pages have several sections in addition to 
those that are conventional for \s-1UNIX\s+1, namely the following:
.nf
.ta .75i

	ESPS PARAMETERS