README file for tops.

Program Tops - a stack-based computing environment
Copyright (C) 1999-2014  Dale R. Williamson

Author: Dale R. Williamson <dale.williamson@prodigy.net>

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software Foundation,
Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

------------------------------------------------------------------------

Description.

tops 3.2.0 (Mon Feb 18 10:48:33 PST 2013)
http://savannah.gnu.org/projects/tops
 
  This program provides a stack-based computing environment.  Four
  types of stack items--numbers, matrices, strings, and arrays of
  strings (called volumes)--are manipulated by commands called
  words.  Words interact through items on the stack, and can be
  assembled as building blocks into new and more powerful words.
 
  The stack and stack items, the catalog and catalog items, and
  simple pattern matching to items in the catalog keep the machine
  running from word to word.  A handful of stack manipulation
  words (like swap, dup, rot, over) allow a user to write phrases
  that juggle items on the stack from earlier words and feed them
  to later words, running the machine with extraordinary inter-
  active control, word by word.  Useful new words and phrases com-
  mitted to text files or scripts can later be run in batch mode.
 
  Numbers on the stack or in matrices can be real or complex, and
  are defined in 64-bit IEEE floating point format for all arith-
  metic operations.  Complex arithmetic makes the program useful
  in a wide range of scientific applications when it is compiled
  to use external scientific packages such as LAPACK (Linear Alge-
  bra PACKage, written in Fortran) and FFTW (Fastest Fourier
  Transform in the West, written in C); see examples below.
 
  Manipulation of the stack and the running of words follows post-
  fix notation, and a writer of postfix phrases is responsible for
  staging operations with the correct precedence.  The program's
  interactive prompt is natural for writing postfix phrases, be-
  cause results appear immediately on the stack, step by step, as
  stack items are set up and words are keyed to consume them and
  create new ones.
 
  Payoff for the effort of writing for a stack machine is speed
  comparable to compiled code when phrases are turned into new
  words called inlines, which are simply higher level words con-
  sisting of machine addresses in postfix order that execute im-
  mediately.
 
  New words operate just like the program's set of native words
  written in C and Fortran that run from the interactive prompt
  or an included file.  Networking, multitasking, text manipula-
  tion and queuing are examples where interactive development of
  postfix words and phrases to control the machine is very con-
  venient.
 
  Capabilities from external packages are easily compiled into
  the program so new words can be written to run their functions.
  In addition to words developed for scientific applications with
  LAPACK and FFTW mentioned above, database program SQLite has
  been used to write words for relational databases, and secure
  network package OpenSSL has been used to enable the program
  running on a number of machines to be configured as a cluster
  of autonomous secure servers and clients with encrypted connec-
  tions.
 
  A multitasker in the program provides the capabilities to set
  alarms and run periodic tasks.  Running at 25 Hz (default), the
  multitasker beats 25 times per second to run multitasker words
  we write at scheduled frequencies.  With the multitasker, the
  program can be made to sense time intervals and run different
  steps, depending, for example, upon what day it is, with no
  user intervention, day after day.
 
  When solving scientific equations, rather than running a series
  of steps to, say, manage sockets with noisy network connections,
  staging stack operations for postfix input is cumbersome due to
  precedence in operations that perform arithmetic.
 
  Infix notation, common to C, Fortran and other programming lan-
  guages, uses algebraic expressions that are more convenient to
  write and that follow well defined rules of precedence for doing
  arithmetic.  Parentheses, brackets and braces are used to iso-
  late terms and force precedence when necessary.  Unlike postfix,
  infix statements cannot be run symbol by symbol, and require a
  parser to turn them into a correct order of sequential opera-
  tions, like postfix, that can run the machine step by step.
 
  For applications better suited to infix notation, the program's
  postfix prompt (called the ready prompt) can be switched to its
  infix prompt by keying >> to begin accepting keyed input that
  is infix (keying << returns the program to its ready prompt).
 
  At the infix prompt, an infix parser of C-like statements and
  matrix bracket notation comes into use that transforms infix
  phrases like these into their postfix analogs and immediately
  runs them:
 
 /* Print postfix for precedence implied by infix expression: */
    P = parse("x = 41 / (5 + 4 * 3 ^ 2);"); dot(P);
 
    i = sqrt(-1); // imaginary number i
 
 // Using the LAPACK package:
 // Eigenvalues and left, right eigenvectors of complex A, real B:
    (Alpha, Beta, VL, VR) = zggev(A, B*(1+0*i));  // B to complex
    lam = Alpha ./ Beta;                          // complex freq
    Lnull = conj(VL)' * A - lam \* conj(VL)' * B; // check left
    Rnull = A * VR - B * VR *\ lam;               // check right
 
 // Using the FFTW package:
 // Complex fast Fourier transform of real A sampled at rate S:
    (Fr, Fi) = FFT(detrend(A, trend(A)), S, rows(A));
    F = complex(Fr, Fi); // real and imaginary into complex F
 
 // Sig(t) is updated to H(t) when P(t) equals S1 or S2
    Sig = looking(H, (P==S1 || P==S2)); // Sig[0] = H[0]
 
    eta = H \* gam[*, 1:cols(gam)/2]; // all rows, left half cols
 
 /* Using << ... >> to embed a postfix phrase into infix (in post-
    fix, items in parentheses are comments): */
    STEPS = (<< H (hr) 60 (min/hr) M (min/step) / * >>);
 
    C = rget(node[3])[*, .C]; /* column .C from rget(node[3]) */
 
 /* Sort all rows of D based upon real part of column 3 of D: */
    Dsort = D[[sort([Re(D[*, 3]) , 1:rows(D)], yes)][*, 2]];
 
  Applications can be written that take advantage of the conven-
  ience and matrix symbols of infix notation and the immediacy of
  postfix notation, all in the same file.
 
  Over 1,500 words exist as concrete examples of tasks in matrix
  analysis, signal processing, sound, voice, text manipulation,
  multitasking and networking.  Words for new applications can be
  written from existing words, using postfix or infix, and sourced
  from text files; or as new words in C or Fortran compiled into
  the program to work alongside existing native words.
 
  Thu Jul  5 04:54:55 PDT 2012.  How to write and test a new word
  in C.
 
  Written for mmaxN() (file wapp.c) but general enough to show
  here.
 
  int mmaxN() // mmaxN (hA n N --- hB) \ moving maximums, N
                                         highest //
 
  As in most functions of this program, arrays in mmaxN() such as
  output matrix B and internal working matrices ride on the stack.
 
  This makes it relatively easy to write, test and debug new words
  in C, as described below for the process used to develop word
  mmaxN().
 
  Place "return 1;" at any line in the word's C code, recompile
  and run the word interactively at the ready prompt.  When the
  word returns, inspect the elements on the stack as they are at
  the return 1 point.
 
  Each array is simply an item on the stack and is available to be
  operated upon at the ready prompt by any word.  From the ready
  prompt, run eview to look at numbers in large arrays with a text
  program like vi or nedit.
 
  A few lines of debug output using gprintf() can be added to show
  indices as a loop runs, or other variables before return.  Their
  output flows to the interactive window of the ready prompt where
  you are working, and can be scrolled back through after the word
  returns.
 
  So the interactive window when running the program interactively
  provides two things: arrays as items on the stack the way they
  are at return 1, and a flow of debug output that can be scrolled
  back through.
 
  Expression return 1; placed in the code is like a breakpoint in
  a debugger, but debuggers cannot get at the arrays and their
  numbers (perhaps thousands of them) the way you can when the
  array is right there as an item on the stack.
 
  As progress is made and new code is added, move "return 1;" and
  "gprintf()" statements further down.  Finally "return 1;" is at
  the bottom, and the word's own return expression can be used
  instead.
 
  When the word finally runs on its own, there is no need to write
  programs to run test cases since words receive input from items
  you can set up on the stack.
 
  Just continue testing as above and run the word through a series
  of test cases and view returned results on the stack.  See this
  word, mmaxN() (C file wapp.c), for the test cases run (and which
  can be run right now by pasting them at the interactive ready
  prompt).
 
  While somewhat tedious (but all programming is), this procedure
  is more direct and far easier because it avoids writing and run-
  ning a separate test program after a function has been written.
  When writing this function is complete, so is its testing--done
  once and for all.
 
Usage: 
  tops -h -i -l -p -v [-c sh] [-d /bin] [-u usrpath] [-s syspath] file
 
Arguments:
  -h    Display this message and halt
  -i    After start up, text read will be infix
  -l    Log file, /tmp/Txx.tops.log, not deleted (xx = Unix PID)
  -p    After start up, text read will be postfix (default)
  -v    Display the program version and halt
 
  -c    Name of the Unix shell program file (default sh)
  -d    Directory of the Unix shell program file (default /bin)
  -u    Define usrpath (default ./), the path to program user
          source files, such as: uboot.v, ukey.v
  -s    Define syspath, the path to program system source files,
          such as: boot.v, file.v, hash.v, key.v, sys.v, xterm.v
  file  Input file name (given last)
 
Argument Notes:
  Input file name is the last argument on the command line
  Runs interactively if last argument is not a file name
  Search path: present directory, then usrpath, then syspath
  File boot.v on the search path is required at program start up
  File uboot.v, if found, is run after boot.v for additional
     user-specific actions during program start up
  If -u is not given, environment variable TOPS_USRPATH is sought,
     pre-defined as in: export TOPS_USRPATH=/opt/tops/mytops/usr
  If -s is not given, environment variable TOPS_SYSPATH or a path
     defined at compile time is used

The preceding was obtained by running "tops -h | less" at the system 
prompt.

------------------------------------------------------------------------

The notes below show how to make the program from its tar file and run 
it, and how to install packages that can be used by the program.

Download the program from:

  http://download.savannah.gnu.org/releases-noredirect/tops/

  http://savannah.nongnu.org/download/tops/

Browse CVS source files:

  http://savannah.nongnu.org/projects/tops

  This jumps directly to CVS and shows files sorted by date, latest on 
  top:

  http://savannah.gnu.org/cgi-bin/viewcvs/tops/tops/?sortby=date#dirlist


The following packages can be downloaded and used with the program:

   OpenSSL: open source functions implementing the Secure Sockets Layer
      (SSL v2/v3) and Transport Layer Security (TLS v1) protocols with 
      a general purpose cryptography library
         http://www.openssl.org/

         March 2011:
            Newest versions OpenSSL 0.9.8r and OpenSSL 1.0.0d are now
            available.  Functions in this program were written using
            OpenSSL 0.9.8, and it has not been verified if they are
            compatible with these newer versions.

   Fast Fourier Transform:
      FFTW: discrete fast Fourier transform
         http://www.fftw.org/

         August 2009:
            Newest FFTW version 3.2.2 contains features that are not
            compatible with FFTW version 2.x.  It has not been verified
            if any of these affect this program's fftw_driver.c inter-
            face functions.  Versions of FFTW that have been success-
            fully used with this program are:
               fftw-3.0.1
               fftw-2.1.3 (now obsolete)
            FFTW.org is maintaining fftw-2.1.5 for legacy users.

   Linear Analysis:
      Lapack: linear analysis of matrix equations; real and complex 
         matrix solution, real and complex eigenanalysis
         http://www.netlib.org/lapack/lapack.tgz (September 2001)

      Atlas: installation tool for Lapack
         http://www.netlib.org/atlas/atlas3.2.1.tgz (September 2001)

      SuperLU: sparse linear equation solution
         http://crd.lbl.gov/~xiaoye/SuperLU/superlu_2.0.tar.gz 
         (December 2003)

   Database:
      SQLite: 
         http://www.hwaci.com/sw/sqlite/download.html
         file sqlite-2.8.6.tar.gz (September 2003)

Notes on building libraries from these packages for use in this program
are given below.

------------------------------------------------------------------------

Putting the program on a machine.

CVS provides the latest version, while the tar file in the download 
directory can be months old.

1. Checking out the program from CVS.  Run this command in the directory
   that contains, or will contain, directory tops/:

    cvs -z3 -d:pserver:anonymous@cvs.sv.nongnu.org:/sources/tops co tops

   Later updating of changed files can be done with this command run in
   the directory that contains directory tops/:

    cvs -z3 -d:pserver:anonymous@cvs.sv.nongnu.org:/sources/tops update

   The update command will change files that have been updated.  If 
   files in src/ have changed, the program is recompiled by running 
   "make" (see step 3; running "make clean; make" will recompile all 
   files and is safest).

2. From tar file tops.tgz: 

   Place file tops.tgz in the directory that is to contain directory
   tops/, and untar the program:

      [user@host] /opt > tar -zxvf tops.tgz

   For versions of tar that do not work with zipped files (use gzip -d
   if gunzip is missing):

      [user@host] /opt > gunzip -c tops.tgz | tar xvf -

------------------------------------------------------------------------

Making the program and running it.

1. Go into the tops directory:

      [user@host] /opt > cd tops

2. A view of the files and directories within directory tops/ will 
   appear something like this:

      [user@host] /opt/tops > ls -F
      admin/      doc/         Makefile.ibm    src/     TODO
      apps/       LICENSE      Makefile.linux  sys/     tx/
      AUTHORS     Makefile     README          test/    usr/
      configure*  Makefile.hp  slice           timing/

3. Configuring a Makefile for your machine with minimal options involves
   running the configure script; then the program is created by running
   make:

      [user@host] /opt/tops > ./configure
      [user@host] /opt/tops > make

4. Immediately running the program:

      [user@host] /opt/tops > src/tops -s sys -u usr
               Tops 2.4.2
      Fri Dec 27 07:05:15 PST 2002
      [tops@host] ready > 

   At the ready prompt, type help for some notes on getting started;
   type exit, quit or bye or Ctrl-D to end.

   If the program fails to run in the window, try running under another
   terminal type such as XTERM, which should be selectable from a system
   menu (try right or left mouse button click).  

   If errors occur during start up, the start up log can be reviewed for
   faults:

      [user@host] /opt/tops > src/tops -s sys -u -usr
       Start up failed.  See log file: /tmp/T1692.tops.log
      [user@host] /opt/tops >

   The start up log echoes words being created and 'info:' milestones
   that show pertinent information as start up progresses; a successful
   start up ends with the line:

      info: start up complete

   If the start up log is not saved, -l forces it to be:

      [user@host] /opt/tops > src/tops -l -s sys -u -usr
       log file kept: /tmp/T1753.tops.log
      [user@host] /opt/tops >

   Note: If start up failed too soon, the message that the log file
   is kept may not appear; look in /tmp for T*tops.log.

5. Setting the environment.  

   When ./configure is run in step 3, the path to directory sys/ will
   be embedded into source file src/sys.c and compiled into the pro-
   gram.

   To use a path name different from this, you can add environment 
   variable TOPS_SYSPATH to file .bashrc or .kshrc as shown next.

   The following lines in your .bashrc or .kshrc file run the program 
   from anywhere using a command called tops.  They also set environ-
   mental variables that the program will use for its paths syspath and 
   usrpath: 

      TOPS=/opt/tops # the directory of step 2

      export TOPS_SYSPATH=$TOPS/sys # system files for the program
      export TOPS_USRPATH=$TOPS/usr # your files for the program

      alias tops='$TOPS/src/tops' # running the executable file

   The program always looks for its files locally, then at TOPS_USRPATH,
   and finally at TOPS_SYSPATH.

   Later, you may want to change TOPS_USRPATH to another location, such
   as:

      export TOPS_USRPATH=/opt/mytops/usr # your files for the program

   to contain your modified .v files (taken from sys/ or from usr/) for
   using the program.  This will make them safe from being overwritten 
   when you install a later version of the program.  

   Alias tops shown above is unnecessary if root installs something like
   the following in a bin accessible to all users:

      [root@host] # ln -s /opt/tops/src/tops /usr/local/bin/tops

   which one can check for:

      [user@host] > which tops
      /usr/local/bin/tops

   For this to work, directory /usr/local/bin will have to be on your 
   PATH.  This is done with the following line in .bashrc or .kshrc:

      export PATH=$PATH:/usr/local/bin/

6. Making online documentation.  

   To create html documentation files, move to admin/ and run doc2html:

      [user@host] /opt/tops/admin > doc2html

   Doc2html will create html documentation in directory tops/doc, and a
   web browser can be used to view it by pasting the full path name for
   file doc/index.html into a browser 'Location:' window:

      file:/opt/tops/doc/index.html

   Documentation of each word is also available at the program's inter-
   active ready prompt using word man, in the form man xxx, as in:
   
      [tops@host] ready > man swap
       Entry for swap:
        swap (x y --- y x)
        exchange the topmost stack items
        synonyms: back, bob, duck, nod, rose
        related: over, pick, roll, rot, rev, depth
        category: stack operator
        defined: native word

   Documentation of each word includes its stack diagram, shown above
   as (x y --- y x) for word swap.  Stack items before firing a word
   are shown on the left side of the diagram--for this example of swap,
   y is topmost on the stack.  After firing swap (by typing swap and 
   pressing Enter), the right side of the stack diagram shows x is on 
   top of the stack.

   The Tab key can be used to fill out matches to partially typed words.
   When there is no unique match, pressing Tab again will show all the
   potential matches.  Here is a view of all words currently in the 
   program that start with letter r, by keying: man r Tab Tab

      [tops@host] ready > man r
       hints: rad/cyc rad/deg rake ram rand random random_text
         ranint ranreal rats reach readop4 real-imag recvec redraw
         refine refs remind remtab remtabf render reorder repeat
         replace replot reprint return return, rev revdate reversed
         revn rewind right rip rm rms roll rolldelta rose rot
         rotating rounded rows rss run runid runlevel running runt
         rview

7. Reading. 

   Files in TOPS_SYSPATH and TOPS_USRPATH are easily viewed from the
   interactive prompt (since the program will fill out the path):

      [tops@host] ready > vim file.v

   or

      [tops@host] ready > view file.v

   See boot.v for a summary of program hierarchy and files.

   Some Unix commands work from the ready prompt, like cd, cp, more, rm,
   ls (and variations on ls: ll and llr).

   File sys.v shows these words run by the program, and they serve as
   examples for writing other shell utilities for working interactively.

------------------------------------------------------------------------

Configuring Makefile.XXX.

   Makefile.XXX will need editing to include more features than are
   specified in the delivered files.

   For example, Makefile.XXX contains compiler switches and library 
   references (initially commented-out) for including libraries from 
   packages FFTW, Lapack, and SQLite.

   Installing these packages is described below. 

   Once a package is installed, the appropriate switches in Makefile.XXX
   can be set and './configure; make' run again from directory tops/.

------------------------------------------------------------------------

Below are notes for installing packages and building libraries for this
program.  

   I. OpenSSL
   II. FFTW and Lapack
   III. SQLite
   IV. SuperLU
   V. Parsing ANSI-compatible video terminal codes

File admin/build_dep is being developed to automate installations. 
SQLite installation method Part B uses build_dep.

------------------------------------------------------------------------

I. OpenSSL

   The installation process creates libraries for OpenSSL that can then
   be included in this program by setting the appropriate switches in 
   Makefile.XXX.

   Download OpenSSL from http://www.openssl.org/source .

   Installing OpenSSL (July 2006):

      After downloading openssl-0.9.8.tar.gz (dated Jul  5 21:19:24, 
      containing 3259550 bytes) to directory /packages, as root run
      tar extract:
         [root@kaffia] /packages # tar -xzvf openssl-0.9.8.tar.gz

      As root in directory /packages/openssl-0.9.8, build and test
      the OpenSSL library:
         [root@kaffia] /packages/openssl-0.9.8 # ./config
         [root@kaffia] /packages/openssl-0.9.8 # make
         [root@kaffia] /packages/openssl-0.9.8 # make test
         [root@kaffia] /packages/openssl-0.9.8 # make install

      This package of examples for OpenSSL by E. Rescorla is recom-
      mended (not required by the program; see Reference 2):
         http://www.rtfm.com/openssl-examples/

   References for OpenSSL:
      1. OpenSSL statement: Implements the Secure Sockets Layer
         (SSL v2/v3) and Transport Layer Security (TLS v1) protocols,
         and provides a general purpose cryptography library
         http://www.openssl.org/

      2. Rescorla, E., "SSL and TLS: Designing and Building Secure
         Systems," Addison-Wesley, 2001, ISBN 0-201-61598-3
         http://www.rtfm.com/openssl-examples/

      3. Viega, J., Matt Messier, and Pravir Chandra, "Network Security
         with OpenSSL," O'Reilly Media, Inc., 2002.

II. FFTW and Lapack

   These notes show how to install FFTW, Lapack, and Atlas (a program 
   used in the compilation of Lapack).

   The installation process creates libraries for these packages that
   can then be included in this program by setting the appropriate 
   switches in Makefile.XXX.

   References for FFTW, Lapack, and Atlas:
      FTTW: http://www.fftw.org 
      Lapack: http://www.netlib.org/lapack/lapack.tgz
      Atlas: http://www.netlib.org/atlas/atlas3.2.1.tgz

   Here are the files of /usr/local/lib after making FFTW, Lapack, and
   Atlas using the steps given below (September 2001):

   [user@localhost.localdomain] /usr/local/lib > ll
   total 12807
   drwxr-xr-x   2 root     root         1024 Sep 28 21:12 ./
   drwxr-xr-x  12 root     root         1024 Sep 28 21:12 ../
   -rw-rw-r--   1 root     root      5011640 Sep 25 20:47 libatlas.a
   -rw-rw-r--   1 root     root       244700 Sep 25 20:38 libcblas.a
   -rw-rw-r--   1 root     root       336890 Sep 25 20:49 libf77blas.a
   -rw-r--r--   1 root     root       281916 Sep 28 21:12 libfftw.a
   -rwxr-xr-x   1 root     root          606 Sep 28 21:12 libfftw.la*
   -rw-rw-r--   1 root     root      6619622 Sep 25 20:49 liblapack.a
   -rw-r--r--   1 root     root       258682 Sep 28 21:12 librfftw.a
   -rwxr-xr-x   1 root     root          609 Sep 28 21:12 librfftw.la*
   -rw-rw-r--   1 root     root       293500 Sep 25 20:27 libtstatlas.a
   [user@localhost.localdomain] /usr/local/lib >

   And these additional files for FFTW land in /usr/local/include:
   [user@localhost.localdomain] /usr/local/include > ll
   total 20
   drwxrwxr-x   2 root     root         1024 Sep 12 12:48 ./
   drwxr-xr-x  12 root     root         1024 Sep 28 21:12 ../
   -rw-r--r--   1 root     root        12462 Sep 28 21:12 fftw.h
   -rw-r--r--   1 root     root         3764 Sep 28 21:12 rfftw.h
   [user@localhost.localdomain] /usr/local/include >

   Detailed steps for installing FFTW and Lapack.

   1. Installing FFTW library (Discrete Fourier Transform), to be used
   by native words in file fttw_driver.c.  File signal.v goes on to use
   these native words for signal processing.

   Here are the steps for making the library:

         ./configure --prefix=/path_where_install
         make
         make install

      If --prefix is not specified, the libraries will appear in
      /usr/local/lib (but must be logged in as root).

   2. Installing Lapack and Atlas libraries (in-core matrix utilities),
   to be used by words in essl.c and lapack.c.  

   Here are the steps for making the libraries:

      Step 1: building Lapack in /scratch.
         cd /scratch
         tar zxfv ~/packages/lapack.tgz
         cd LAPACK
         cp INSTALL/make.inc.LINUX make.inc
         make # takes 20 minutes to 2 hours depending on machine

         Produces:
            /scratch/lapack_Linux_XXX.a
         where XXX.a is a name you provide, like XXX.a=PII.a

      Step 2: building Atlas in /scratch.
         cd /scratch
         tar zxfv ~/packages/atlas/3.2.1.tgz
         cd ATLAS
         make # runs interactive config script

         Before running the make command from the completed config
         script, copy the Lapack library of step 1 to a directory
         under /scratch/ATLAS/lib/.  See details in file
         /scratch/ATLAS/doc/LAPACK.txt (line 16).

         Now run make:
         make install arch=Linux_PII # example of a make
                                     # command made by config

         When complete, lib files .a will be in
            /scratch/ATLAS/lib/PII

      Step 3: move the lib files from /scrach to /usr/local/lib and 
      they will be consistent with the names in Makefile.linux; 
      contents should look like the listing of /usr/local/lib shown 
      above.

------------------------------------------------------------------------

III. SQLite

   Part B shows a newer approach using admin/build_dep that supercedes 
   part A, which remains here just for its instructional value.

   A. These notes detail the installation of SQLite.  Part B shows a
   more recent approach that supercedes this part A.

   The download site for SQLite is:

      http://www.hwaci.com/sw/sqlite/download.html

   This latest version was downloaded in September 2003:

      file sqlite-2.8.6.tar.gz 831189 bytes, version 2.8.6 of CVS tree

   1. These are the steps, run by root, that install SQLite:

      /download # mkdir /usr/local/sqlite
      /download # mv sqlite-2.8.6.tar.gz /usr/local/sqlite
      /download # cd /usr/local/sqlite                    

      /usr/local/sqlite # tar -zxvf sqlite-2.8.6.tar.gz 
      /usr/local/sqlite # mkdir bld
      /usr/local/sqlite # cd bld

      /usr/local/sqlite/bld # /usr/local/sqlite/sqlite/configure
      /usr/local/sqlite/bld # make
      /usr/local/sqlite/bld # cd ../

      /usr/local/sqlite # ln -s /usr/local/sqlite/sqlite/src/ include
      /usr/local/sqlite # ln -s /usr/local/sqlite/bld/.libs/ lib

   2. Here is a view of completed directory /usr/local/sqlite:  

      [root@clacker] /usr/local/sqlite # ll
      drwxr-sr-x  3 root  root    4096 Sep 22 07:42 bld/
      lrwxrwxrwx  1 root  root      28 Sep 22 07:45 include -> 
         /usr/local/sqlite/sqlite/src/
      lrwxrwxrwx  1 root  root      27 Sep 22 07:47 lib -> 
         /usr/local/sqlite/bld/.libs/
      drwxrwxr-x  9 root  root    4096 Sep 22 08:48 sqlite/
      -rw-r--r--  1 root  root  831189 Sep 22 07:09 sqlite-2.8.6.tar.gz

   3. The following lines in this program's Makefile.* refer to the lib
   and include links created above.  They can be uncommented:

      SQLITE_LIB= -L/usr/local/sqlite/lib -lsqlite
      SQLITE_INC= -I/usr/local/sqlite/include                                 
   4. User file .bashrc needs a LD_LIBRARY_PATH.  The following shows 
   adding /usr/local/sqlite/lib to an existing LD_LIBRARY_PATH:

      export LD_LIBRARY_PATH=/home/user/mytops/txdir:/opt/tops/tops/tx/
      export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/sqlite/lib/

   B. Building and installing SQLite using admin/build_dep.

   From directory tops/, build_dep is used to build SQLite and install 
   it into /usr/local/sqlite-3.0.7.  It uses the "su -c" command to do 
   the make install step, so you'll be prompted for root password.  

   Alternatively to install into a directory where you don't need root 
   privileges to write into, just replace "/usr/local" with the base 
   directory, i.e. "/home/al" would mean SQLite will go into 
   /home/al/sqlite-3.0.7. 

   This will take a few minutes to build SQLite:
      /opt/tops % admin/build_dep sqlite /tmp /usr/local

   Root creates a symbolic link to the sqlite3 executable:
      # ln -s /usr/local/sqlite-3.0.7/bin/sqlite3 /usr/local/bin/sqlite

   User file .bashrc needs a LD_LIBRARY_PATH.  The following shows 
   adding an SQLite path to an existing LD_LIBRARY_PATH:

     export LD_LIBRARY_PATH=/home/user/mytops/txdir:/opt/tops/tops/tx/
     export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/sqlite-3.0.7/lib

   Tweak SQLite stdout format by setting .sqliterc values (optional):
      % echo ".header on"   >  ~/.sqliterc
      % echo ".mode column" >> ~/.sqliterc

   Here is a script to create a simple database:
      # create a simple database
      rm -f test.db
      echo "create table t(a text, b integer);"      | sqlite test.db
      echo "insert into t values ('cat', 'felix');"  | sqlite test.db
      echo "insert into t values ('dog', 'scooby');" | sqlite test.db

      # show all the values:
      echo "select * from t;"                        | sqlite test.db

   The script should give the following output:
      a           b
      ----------  ----------
      cat         felix
      dog         scooby

   Edit tops/Makefile.linux so that it includes SQL references:
      Append switch -DSQLITE to the list with C_COMOPTS

      and set these:

         SQLITE_LIB= -L/usr/local/sqlite-3.0.7/lib -lsqlite3
         SQLITE_INC= -I/usr/local/sqlite-3.0.7/include

   Build tops again, and things are ready to go with SQLite:
      /opt/tops % make clean; make

------------------------------------------------------------------------

IV. SuperLU

   These notes detail the installation of SuperLU.

   The download site for SuperLU is:
         http://crd.lbl.gov/~xiaoye/SuperLU/superlu_2.0.tar.gz 
         (December 2003)

   Running admin/buildsu will download the SuperLU tar file and build 
   the SuperLU library in /tmp.

   Root copying /tmp/superlu to /usr/local/ will make available the
   library and include files required by this program's Makefile.XXX
   files.  

   Here are the files at /usr/local in superlu/lib and superlu/include:

   [root@clacker] /usr/local/superlu/lib # ll
   drwxr-sr-x    2 root     root         4096 Dec 20 09:54 ./
   drwxr-sr-x    4 root     root         4096 Dec 20 09:53 ../
   -rw-r--r--    1 root     comm       443502 Dec 20 09:41 libsuperlu.a

   [root@clacker] /usr/local/superlu/include # ll
   drwxr-sr-x    2 root     root         4096 Dec 20 09:54 ./
   drwxr-sr-x    4 root     root         4096 Dec 20 09:53 ../
   -rw-r--r--    1 root     comm         4762 Dec 20 09:41 Cnames.h
   -rw-r--r--    1 root     comm         2485 Dec 20 09:41 colamd.h
   -rw-r--r--    1 root     comm         9819 Dec 20 09:41 csp_defs.h
   -rw-r--r--    1 root     comm         1606 Dec 20 09:41 dcomplex.h
   -rw-r--r--    1 root     comm         9710 Dec 20 09:41 dsp_defs.h
   -rw-r--r--    1 root     comm         1536 Dec 20 09:41 scomplex.h
   -rw-r--r--    1 root     comm         9635 Dec 20 09:41 ssp_defs.h
   -rw-r--r--    1 root     comm         5859 Dec 20 09:41 supermatrix.h
   -rw-r--r--    1 root     comm         3385 Dec 20 09:41 util.h
   -rw-r--r--    1 root     comm        10138 Dec 20 09:41 zsp_defs.h

   Then it is simply a matter of uncommenting the SuperLU library file
   and include file references in Makefile.XXX and adding the -DSUPER 
   switch to the list of compiler options, C_COMOPTS, and then running
   "make clean;make."

------------------------------------------------------------------------

V. Parsing ANSI-compatible video terminal codes

   A finite state machine for parsing ANSI escape and control sequences
   is presented in the following: 

      http://www.vt100.net/emu/dec_ansi_parser ,

   and an implementation in C is in the following public domain file:

      http://www.vt100.net/emu/vtparse.tar.gz .

   A copy of vtparse.tar.gz (4763 bytes), with source files dated 
   Sep 10, 2005, is contained in usr/telnetd.  It requires Ruby to
   create a parse tables file, vtparse_table.c, prior to compiling.

   Here is an example of building the vtparse library used by this pro-
   gram under the -DVT compiler switch (but see Update below):

     /usr/local # tar -zxvf vtparse.tar.gz
     /usr/local # mv vtparse.tar.gz vtparse
     /usr/local # cd vtparse
     /usr/local/vtparse # make
     /usr/local/vtparse # gcc -c vtparse.c vtparse_table.c
     /usr/local/vtparse # ar -crs libvtparse.a vtparse.o vtparse_table.o

   Place the following in the relevant tops/Makefile.XXXX:

      VTPARSE_LIB= -L/usr/local/vtparse -lvtparse
      VTPARSE_INC= -I/usr/local/vtparse

   and specify compiler switch -DVT (or -DVTAIX for ibm).

   Update. 
   For portability, untarred copies of files after Ruby processing are 
   included in usr/telnetd, and it is not necessary to build vtparse in
   /usr/local.  An alternate procedure for building the vtparse library
   for the program is as follows:  

      [user@host] /opt/tops > cd usr/telnetd
      [user@host] /opt/tops/usr/telnetd > make_lvtparse
      [user@host] /opt/tops/usr/telnetd > ls *.h lib*
      libvtparse.a  vtparse.h  vtparse_table.h

   After running make_lvtparse, command ls shows that the required .h 
   include files and library file libvtparse.a are present.  References
   to these are made in tops/Makefile.XXXX as follows, using the path 
   to this point relative to the compilation directory tops/src:

      VTPARSE_LIB= -L../usr/telnetd -lvtparse
      VTPARSE_INC= -I../usr/telnetd

   and compiler switch -DVT (or -DVTAIX for ibm) is specified.

------------------------------------------------------------------------
