README for
SAM Kernel and Application
Updated 2020-03-24

Copyright (C) 2010, 2011, 2012, 2015, 2018, 2019, 2020 Joseph Rosevear



Current State of changlog.txt files

vvv
44	1079126912 040312 21:28	./opt/SAM_modules/example/changlog.txt1
20	1100250962 041112 09:16	./opt/SAM_modules/example/changlog.txt2
20	1155911362 060818 14:29	./opt/SAM_modules/example/changlog.txt4
20	1195940814 071124 21:46	./opt/SAM_modules/example/changlog.txt5
20	1199459327 080104 15:08	./opt/SAM_modules/example/changlog.txt3
12	1523143238 180407 23:20	./opt/SAM_modules/kernel/changlog.txt
20	1556293820 190426 15:50	./opt/SAM_modules/example/changlog.txt6
16	1572791505 191103 14:31	./opt/SAM_modules/main/changlog.txt
8	1575326423 191202 22:40	./opt/SAM_modules/tool/changlog.txt
8	1584805983 200321 15:53	./opt/SAM_modules/example/changlog.txt
12	1584855642 200322 05:40	./changlog.txt
4	1584989704 200323 18:55	./opt/SAM_modules/pkg_tool/changlog.txt
^^^

Scope

Always refer to your distribution of SAM for the best documentation.


What is "SAM Kernel and Application"?

   SAM is a command-line tool that has two parts, a core (or kernel)
   and an application.  The kernel is C-code and Bash scripts and
   functions.  It can be used together with a SAM application to manage
   your own command-line executables.  It does this by controlling the
   shell environment.  I have created both the SAM kernel and a handy,
   example SAM application.  SAM runs on Slackware Linux.

   Both the SAM Kernel and the Application are distributed under the GNU
   General Public License--see the accompanying "COPYING" file for more
   details.

   The Application is also known as SAM-GLS or "An Application of SAM
   for GNU/Linux Slackware.  The Kernel and Application together are
   called "SAM".

What does the name "SAM" mean?

   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".  It was a menu-based collection of
   programs used for analysis of aerospace structures.  Although none
   of the code in this distribution is from the General Dynamics' SAM,
   they do both display text (or ASCII) menus as a way of managing Code
   and so share the same spirit.

On what hardware does SAM run?

   The SAM Kernel in this distribution contains a few small C
   executables that have been compiled to run on a PC.  If you would
   like to compile these again, then I expect you could run SAM on any
   hardware.  (See software requirements, below.)

   I don't think there is any other code in this distribution that
   needs compiling or would, for any reason, affect what hardware could
   be used.

What are the software requirements?

   SAM actually worked in Ubuntu (I tested an earlier version), if I
   changed /bin/sh to point to /bin/bash and provided a real root
   account.  I need to document this more throughly, so for now let's
   just say that Slackware is required.  I have used SAM in Slackware
   7.1, 10.0, 10.2, 12.0, 13.0, 13.1, 13.37, 14.1, and 14.2.  It is
   quite likely that it will work OK in other versions.

Documentation

   There are several sources of documentation provided.  Besides this
   file (that you are reading) file CONTENTS in the main module
   ($sam_distro) and file GUIDE at the root ($sam_root) of this release
   will get you started.  File GUIDE will refer you to other sources.

Compiling SAM

   As I mentioned above, The SAM Kernel uses a few small C executables
   that have already been compiled for you (for use on a PC).  If you
   would like to compile them again, for any reason, please do so.  The
   source code has been provided.

Installing SAM

   First you need to get a SAM archive, preferably the latest one.  You
   will need to unzip it to a suitable location.  I recommend that you
   install it to the root of a flash drive.  I will walk you through
   the steps to do this below:

   1.  Get a suitable flash drive.  SAM is small (less than 125 MB), so
   it will fit comfortably on any modern flashdrive.

   You will probably want to start with a new flash drive.  Either that
   or find one you don't mind wiping or one that has an existing
   optimally aligned partition of at least 4 GB.

   2.  If necessary make a partition (again it should be optimally
   aligned), and make a Linux file system.  I recommend an ext4
   partition with journaling removed.  Instead set it up to do periodic
   file system checks.

   3.  Mount the flash drive anywhere, and cd to root of the flash
   drive.

   4.  Now run (as root)

      tar -xvvzf <path to the SAM archive>

   This will install SAM (kernel and application including all the SAM
   modules) to the mounted flash drive.

   It is now ready to run.

   Please find the documentation at the locations named above. 

   No configuring is needed at this stage unless you are using a very
   old version of Slackware.  This is not likely, but if you are using
   a version of Slackware that is older than 10.0, then you may need to
   change file $sam_root/bprofile to use

      export sam_set_version=1

   instead of

      export sam_set_version=2

   Hopefully, that will fix it.

   Now you can run SAM.  See "Running SAM" below.

Running SAM

   $sam_root/bstart will work to run SAM, if you first set and export
   the necessary variables and create $sam_temp_base, but normally you
   should use $sam_root/begin.  It takes care of setting/exporting
   variables and making $sam_temp_base for you.  Then after running
   begin, you can recursively start SAM using $sam_root/bstart.  There
   are also other ways to run SAM.  See $sam_root/GUIDE and
   $sam_distro/sam/GUIDE-K for how to run SAM.

Maintainers

   I (Joseph Rosevear) maintain the software in this release.  Find my
   contact information in file "$sam_distro/data/author.dat".

   Or you can read my contact information by running SAM and entering

      about; author; bye
