.lo.SJ "Adding Local Functions to ESPS".AU "Alan Parker".TM ETM-S-88-W1 1.2 6/27/88.*RETM-S-86-14, Entropic Signal Processing System (ESPS) Programming Guidelines.*RETM-S-87-29, Installation Instructions for the Entropic SignalProcessing System (ESPS).sh 1 Introduction.lpThe document describes the procedure for adding local functions to ESPS.It should be read after the above references.  It is suggested that thefirst time ESPS is installed, it should be a normal installation; thatis, installed as shipped, without any local modifications..lpESPS has been designed to easily support the addition of local libraryfunctions, file types, and programs.   This is accomplished by havingthe installation script support the notion of a local sourcedirectory, from which it will run a installation script.  This script is likethe primary installation script.   This mechanism can also support\fIoverloading\fR standard ESPS programs or library functions, whichmodified ones.  .sh 1 "The ESPS Source Directories".lpAll of the standard ESPS programs and functions are under the directory\fIgeneral\fR.   For details of the directory structure, see reference (1).If you have a local section, you would place theseprograms under another directory (any name will do) that is a peer of\fIgeneral\fR and has a structure like that of\fIgeneral\fR.    A skeleton local directory, \fIlocal.skel\fR is provided on theESPS distribution to aid in building your local directory.  Itsstructure is show here:.(b.ft CW.nf                |-h-------------                |                |               |-man1----------|-local.skel----|-man-----------|-man3----------                |               |-man5----------                |                |-src-----------|-example-------                                |-lib-----------.fi.)b.ft LRIn the local directory, there is a installation script, that is calledby the primary installation script..sh 1 "Specific Directions to Create Local Functions or Programs".lpTo create either one or more local library functions, programs, or both,the first thing to do is to create your local directory.   The easiestway to do this is to simply rename \fIlocal.skel\fR to \fIlocal.XXX\fR,where XXX is something reasonable for your site.     You must also editthe primary installation script \fIgeneral/install\fR.   There are threedefines in the primary installations script that control the compilationof local items.  They are: \fBDOLOCAL\fR, \fBLOCALDIR\fR, and\fBLOCAL\fR.   \fBDOLOCAL\fR is set to y (yes) or n (no) to indicatewhether the local part of ESPS should be installed when the script isrun.   If you want to install your local part, this variable must be y.\fBLOCALDIR\fR is set to the name of the local directory (default tolocal.skel).  \fBLOCAL\fR is set to the a symbol that you wish to definewith the \fIcc\fR \fB-D\fR option for your local part.  It must bedefined even if you do not need such a symbol.  For example, we use\fB-DESI\fR for our local part..lpIn the following descriptions, where the name \fIlocal.skel\fR is usedyou should substitute you own directory name if you changed it..sh 2 "Creating Local Library Functions".lpLocal library functions are handled by creating a separate local library(normally called \fIlibespsl.a\fR) in the ESPS \fIlib\fR directory.   Thesources for the local library functions are in \fIlocal.skel/src/lib\fR.This directory also contains the library makefile and lint library source..lpTo create a local library (with one or more functions) add the .c filethat implements this function to this directory and add the correctinstructions to the makefile in this directory.   Use the sample file asa model, or consult the \fIgeneral/src/lib\fR directory for more complexexamples.  For the first file you add to the local library, replace thesample file, \fIfoo.c\fR with your C file.   It is a good idea, but notmandatory, to add the new function to the lint library source file.  Usethe standard lint library source file as an example, or consult the\fImake\fR manual page..lpIf you also are adding any local header files (.h) these should be addedto the directory \fIlocal.skel/h\fR.   The makefile in this directorymust also be updated.  There is an empty example file in that directoryto show how the entry goes into the makefile.   .sh 2 "Creating Local Programs".lpLocal user-level programs are handled by creating a source directory forthe new program under the \fIlocal.skel/src\fR directory.   There is atrivial example directory there to provide some guidance.  This sourcedirectory must contain all of the source files and a ESPS compatiblemakefile.  Use the one in \fIlocal.skel/src/example\fR as a prototype.The name of the source directory (usually the same as the program) mustbe added to the local installation script (\Ilocal.skel/install\fR).Search for the shell variable \fBDIRS\fR and add the directory name to the list there..lpNote that a local program might be one of the standard ESPS programswith some local changes.   If you want to change a standard ESPS programit is best to copy it into the local section and then make your changes.Unless you want both versions of the binary avaialble to your users, youdo not need to change the name.   Assuming the user's search path is setup correctly (described below), the local version will be found beforethe the standard version.   If you use this procedure when you need tomodify one of the standard programs, you will not run the risk of losingchanges when you receive an update to ESPS.  (Of course, copying generalprograms to the local directory and making modifications does not changethe proprietary nature of Entropic's source code and the modified codeis still subject to the license agreement that your organizationsigned.).sh 2 "Compiling the Local Section".lpAfter the new programs have been added to the \fIlocal.skel\fR directoryas described above, the primary installation script must be rerun to executethe local script.   Change to the \fIgeneral\fR directory and give thecommand \fBinstall none\fR.   The argument to the install command tellsit a directory (in \fIgeneral/src\fR) to install; the default if nothing isgiven is to install all programs.    The directory \fInone\fR is anempty directory in \fIgeneral\fR that can serve as the target for aninstall command without really doing anything..lpThis command will run the general installation script and then run thelocal installation script, which should install all of your localprograms..lpAfter the local installation script has been run one time, you can usethe programs \fIlemake\fR and \fIlecc\fR to compile local programs.These are scripts, generated by the local installation script, thatdefine the ESPS local compilation environment and then run regular Unix\fImake\fR or \fIcc\fR.   So to recompile the local library later, you canjust change into \fIlocal.skel/src/lib\fR and type \fBlemakeinstall\fR..sh 1 "Making Private Local Programs".lpPrivate copies of ESPS programs can be maintained in a user's directoryby using the ESPS scripts \fIemake\fR and \fIecc\fR.  These are scriptsthat define the ESPS compilation environment (header file and librarylocation, floating point option, and binary directory) and call the Unixcompilation tools.    If the private program uses features that are onlyin your location section (either local header files, or a local libraryfunction), then you should use \fIlemake\fR and \fIlecc\fR.  The onlydifference between \fIlemake\fR and \fIemake\fR is that \fIlemake\fRdefines the local library and header files.   The local library andheader files are searched first, so a local library function by the samename as a general function well be used instead..sh 1 "A Word about Search Paths".lpOf course, the ESPS binary directory must be on your user's search pathin order for them to have easy access to the ESPS programs.   Normallythe ESPS binaries go into the directory \fIbin\fR of the ESPS targetdirectory (normally \fI/usr/esps\fR, but controlled by parameters in theprimary installation script).   Local programs go into \fIbin.local\fR.So \fIbin.local\fR and \fIbin\fR must both on the user's path.  Thecorrect thing to do is to put \fIbin.local\fR on the path first, so thatif there is a program by the same name in the local part and the generalpart, the user will get the local version by default..lpFor example a typical path statement might be:.(b.ft CW.nfset path=(. /usr/esps/bin.local /usr/esps/bin /usr/local /usr/bin /bin).fi.)b.ft LR