README for
SAM Kernel
Updated 2015-03-31

Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008, 2010, 2011, 2012,
2015 Joseph Rosevear



WHAT IS THE SAM KERNEL?

   The SAM kernel is distributed under the GNU General Public
   License--see the accompanying "COPYING" file for more details.

   The SAM kernel is the core, or heart, of SAM.  SAM consists of the
   kernel plus an application.  I have also developed an application
   which should be included in this distribution.

   SAM is a script-able, text-based menuing system written from scratch
   by me, Joseph Rosevear.  It runs on computers hosting a GNU/Linux
   operating system.

   SAM provides an environment of functions, scripts, and executables
   which work together to provide a menuing system.  This system allows
   control of the PATH variable in a way that is coordinated with
   changes to the prompt and menus that are displayed.  The result is a
   system in which available commands and other notes pertinent to the
   current PATH are displayed in user-made menus.

   When set up appropriately, multiple instances of SAM can run
   simultaneously either from separate consoles or recursively.

   The SAM kernel is small, simple (it is made mostly of shell scripts
   and uses text files for menus), and unobtrusive (there is nothing
   between you and the Bash shell when you are in SAM).

   Note that SAM's simplicity is good in some ways, but, like the C
   programming language, it's simplicity gives the user much
   responsibility.  To be a good SAM user you need to be familiar with
   Bash shell programming.

WHAT DOES THE NAME "SAM" MEAN?

   Officially, SAM stands for for "simple ASCII menus."  It has a
   history, however.  It was inspired by a system I worked with as an
   engineer for General Dynamics, Space Systems Division.  That system
   was called the "Structural Analysis Menu" or something like that. 
   It was a menu-based collection of programs used for analysis of
   aerospace structures.  None of the code is from that original SAM,
   in fact, its architecture is not even close.  Yet it retains the
   original spirit.

ON WHAT HARDWARE DOES SAM RUN?

   Good question.  SAM was developed on a PC with a 433 MHz Celeron
   processor.  I now have a PC with a 2.00 GHz Pentium 4 processor, and
   it runs SAM too.  Because SAM is simple, I expect that it will run
   on any hardware.

WHAT ARE THE SOFTWARE REQUIREMENTS?

   Also a good question.  I have previously used SAM in Slackware 7.1,
   10.0, and 10.2, 12.0 and 13.1.  I'm currently using SAM in Slackware
   13.37.

   SAM actually runs in Ubuntu if you change /bin/sh to point to
   /bin/bash and make a real root account.  Since this needs some
   documenting, lets just say for now that Slackware is required. 
   Certainly you will need some kind of GNU/Linux to run SAM. 
   Furthermore, SAM interacts with the Bash shell and has scripts that
   use commands in /bin and /usr/bin.  Your shell, /bin and
   /usr/bin may have to be equivalent to what is in Slackware.

   The SAM kernel uses an assortment of functions, scripts and
   executables.  There is a slim chance that you may have a function,
   script, executable or alias already installed that has the same name
   as one belonging to the kernel.  I leave it up to you to check for this
   possibility and deal with it.  The kernel puts its commands first in
   PATH, and the (other) locations which it adds to PATH it puts last.  Note
   that some of the kernel's commands are not visible to you in its
   menu, because they are used internally by SAM.  (On the other hand,
   many of the kernel's commands are visible and intended for common
   usage.) The kernel is not large.  With a little sleuthing you should
   be able to discover what functions, scripts and executables the
   kernel uses.  And you can always type "which" to see what you are
   getting.  (SAM runs hash -r for you.)

   Likewise, be aware that SAM sets many variables.  It does this in a
   shell, so nothing will be changed in the environment from which you
   start SAM.  While running SAM, however, you may find a variable that
   you need is already in use by SAM.  Again I leave dealing with this
   to you.

DOCUMENTATION:

   Besides this file there is also file GUIDE in the main package. File
   GUIDE gives some important information and refers you to other
   sources.

INSTALLING THE SAM KERNEL:

   When installing and using SAM it is good to understand the
   difference between the SAM kernel and the SAM application.

   In this distribution the SAM kernel exists as a Slackware package,
   so using the Slackware installpkg command will install it correctly.

   If you wish to install the SAM kernel by hand you need to know that
   normally the kernel is installed to /opt/SAM_pkgs/kernel.  If you
   have a copy of the unpacked kernel you may simply copy it to this
   location.  Be aware that /opt/SAM/sam is a link that points to
   /opt/SAM_pkgs/kernel (The SAM kernel).  Be sure when you copy you do
   something like "cp -Rpdi <location> /opt/SAM".  The -d in this will
   cause the links to be copied as links.

   The SAM kernel will not do much without an application, so unless
   you have one already, you will want to install that also.  Note that
   although the kernel is distributed in a single Slackware package,
   the application can be made from one package (called "main") or
   from several packages.

COMPILING THE SAM KERNEL:

   Although the SAM kernel (together with a suitable application) will
   run without changes on PC's like mine, there are three C executables
   in it that you may want to compile for various reasons.  No problem. 
   Just compile.  There are no make files.  The source file names
   correspond to the executable names.

MAINTAINERS:

   I (Joseph Rosevear) maintain the SAM kernel.  Find my contact
   information in file /data/author.dat in the main SAM package
   (sam-main).  Once installed this file will be at
   "$sam_distro/data/author.dat" which is normally
   "/opt/SAM_pkgs/main/data/author.dat".

   Or you can read my contact information by starting SAM and entering
   this:

      about; author; bye
