SAM Kernel and Application
Updated 3-27-18

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



1.  A short table of references in this distribution.

2.  What is this?

3.  Some terminology.

4.  Installing this Application of SAM for GNU/Linux.

5.  Running SAM.

6.  Using SAM.

7.  About SAM menus.

8.  Special variables.

9.  There is a nuisance you may encounter.

10. A diagram of files and dirs in /var/opt.

11. Shells used.

***


1.  Informative files in this distribution.

distro                tips
------                ----
CONTENTS              README
COPYING               env-note.txt
GUIDE
GUIDE-K
README


2.  What is this?  This is a distribution of SAM Kernel and Application
and was written by me, Joseph Rosevear.  See file COPYING in this
distribution for a statement of the license agreement.  (Refer to the
COPYING file in the "main" package.)


3.  Some terminology.  This is a distribution of SAM Kernel and
Application which is also known as "SAM" (upper case).  SAM uses
variable "sam" (lower case) which is set to the installed location of
the SAM kernel.  The SAM kernel is provided in a single package.

The SAM application is also known as An Application of SAM for
GNU/Linux Slackware or SAM-GLS.  It consists of one required and other
optional packages each of which installs to its own location.  The
required package uses symbolic links to make it appear as the root of
the whole installed distribution.

SAM uses a symbolic link SAM -> SAM_pkgs/main.  SAM also uses a
variable "sam_distro" which points to the location of this link (using
its full path).  Considering this and the above paragraph, we can
therefore refer to the whole distribution as SAM or $sam_distro.  (I
prefer to use $sam_distro.)

SAM uses a symbolic link SAM/sam -> ../kernel.  We can therefore refer
to the kernel as $sam or SAM/sam.  (I prefer to use $sam.)


4.  Installation of SAM.

First I need to tell you about SAM packages.  They are traditional
Slackware packages and end with ".tgz".  The names of the packages in
this distribution are given below, but I have left the date part of the
name off.  I use names that contain a "date string", the date plus two
letters (e.g., "100822aa"), instead of version numbers.  So, a SAM
kernel package might be named

   sam-kernel-100822aa.tgz

for example.

The date strings are important, because they identify the distribution. 
To insure compatibility, use only SAM packages from the same
distribution (packages that have the same date string).

This distribution includes several Slackware packages.  They can be
installed in the usual Slackware way using installpkg.  A minimum
installation includes includes these two packages:

   sam-kernel      The SAM Kernel.
   sam-main        This SAM-GLS package is required, the
                   others are optional.

You may optionally install these other SAM-GLS packages:

   sam-example     Large set of examples of use of SAM.
   sam-tool        Tools for SAM.  Recommended.
   sam-pkg_tool    Slackware package tools.

This is the structure of SAM after installation:

/opt
   SAM_pkgs
      example  (optional)
      kernel   (required)
      main     (required)
      pkg_tool (optional)
      tool     (optional, but recommended)

Note that besides installing your choice of packages you need also to
deal with some variables.  Two of these which are critical are
sam_temp_base and sam_set_version.  They need to be set and exported. 
Another, glos, should be unset.  I recommend that you deal with these
variables in your ~/.bash_profile.  See /opt/SAM/tips/README for the
details.

And you must make a symbolic link /opt/SAM -> /opt/SAM_pkgs/main.
(Slackware installpkg should make this automatically, but you can make
it by hand if needed.)

You may feel a need to change your PATH variable to aid in running SAM,
but I don't recommend it.  See the section below, Running SAM, to learn
what to do.


5.  Running SAM.

The word "run" is a little misleading here.  There is code that is run
to begin SAM and to end SAM.  This code runs in the usual sense.  But
in between beginning and ending nothing is running, not even a daemon
or a process in the background.  SAM is similar to an old piece of
software for the Commodore 64 called the "DOS Wedge" in this way.  It
gets the work done not by running, but by changing how things run.  SAM
does this by manipulating the environment.  It changes the PATH
variable and other variables, and it sets and unsets variables and
functions.

I needed to explain this, but I will not talk about it anymore.  I will
use the word "run" in reference to SAM and expect you to understand
what it means.  Here, then, is what you need to know about "Running
SAM":

There are four scripts that are used to run SAM.  They are "begin",
"bree", "breekit" and "bstart".  Each runs SAM in a slightly different
way.  You can find them at /opt/SAM, and you can use them from this
location.  For example, you can enter

   /opt/SAM/bstart

and SAM will run.  You will know that SAM is running by the changed
prompt.  (SAM has a two-line prompt.)  To exit from SAM enter "bye" or
"exit".

Each of these four scripts can be used directly by naming its full
path, as I have shown above, and that is fine to do.  However, each
user should also copy each of these to his directory in /home.  In this
location they can be safely customized.  (You may give them new names.)
By "safely" I mean that this way you don't risk confusing the state of
your SAM installation.

Root should do this too, but only for the scripts "begin" and "bstart".
Root should not use bree or breekit.  These scripts provide root
authority.  Root already has root authority, so something confusing
would probably result.

After copying these scripts to your directory in home or to /root, then
they can be used by prefixing "~/" to the command.  Note that "bree"
and "bstart" are found in /opt/SAM, and "begin" and "breekit" are in
/opt/SAM/tips.

Here are explanations of the use of "begin", "bree", "breekit" and
"bstart":


   begin          Uses bstart to run SAM for ordinary users and root.

   bree           Runs SAM again from an environment in which it is
                  already running.  The new instance becomes root and
                  inherits the previous environment.  It should be run
                  by an ordinary user (not root).

   breekit        Uses bstart to run SAM, and then bree to run SAM
                  again (recursively) as root.  It should be run by an
                  ordinary user (not root).

   bstart         Runs SAM for ordinary users and root.


6.  Using SAM.

After invoking SAM you will have a menu on your screen.  You can scroll
up and down with the up and down arrows.  (You are actually using the
"less" command.) Pressing "q" returns you to the command prompt.  Enter
"menu" to display the menu again.

Enter commands from the menus to do the things described by the menus.

This (above) may confuse some users.  Some people expect a menu to have
automation built in so that you click with a mouse and something
happens.  SAM's menus don't work that way.  I insist that they are
still menus, but I admit that they are not "traditional" menus.

Use "exit" to leave SAM.

Use "bye" to leave a menu and return to the previous one.  When there is no
previous menu "bye" will take you all the way out of SAM.

Use ";" to separate commands on one line.  This is a feature of Bash,
not of SAM, but it works well in SAM.


7.  About SAM menus.

A menu for sam is a file named "menu.dat".  Make one and put it in a
directory, and it will be displayed by the use of the command

   menu

when it is the "local" menu.  To make a menu local (and the directory
that it is in) use the "bound" command.

I will illustrate with an example, but first I need to mention my use
of the term "local".  That is my term.  I invented it.  When using SAM
a directory can be "current" and it can also be "local".  These two are
independent.

A directory is current when you are in it.  You go into a directory by
using "cd".  That is nothing new.  A directory is "local" when you
"bound" to it.  Here is an important concept:

   I will often refer to a menu as being local.  That is just a short
   way of saying "the directory is local, and it has a menu that is
   intended to describe the available commands in that directory".

   I won't explain this again.  When I talk about a menu being local,
   please understand it to mean what I have explained above.

Here is an example (you will need to be in Slackware 10.0 or more
recent.  See file /opt/SAM/tips/README for more information.):

   export sam_temp_base=/tmp
   export sam_set_version=2
   /opt/SAM/bstart
   echo test > /tmp/menu.dat
   bound /tmp
   bye
 
See /opt/SAM/tips/README to understand the first two lines. The third
line runs SAM.  You will probably need to enter "q" to leave the menu
viewer (less).  You will probably need to do this twice in this
example.  Then next line makes a menu that contains the word "test". 
That is not very useful, but it gets us started.  Then the example
makes the new menu local ("bound /tmp" does this).  The "menu" command
causes the menu to be displayed, and "bye" will exit SAM.

Here is the menu that you will see after entering "bound /tmp":

vvv

/tmp

local  {
 COMMAND       DESCRIPTION
test

global {
 COMMAND       DESCRIPTION
Builtin     --
    exit       Closes the current shell.  If SAM was started in the
                current shell, then exit will terminate SAM.
in $sam     --
   about       Menu about the SAM kernel including the following:
               author, documentation, license, ABSOLUTELY NO WARRANTY,
               redistribution.

   bound       Adds $1 to PATH.  This is not inherited by subsequent
               synthetic shells.  Also adds $2 (if any) to PATH.  This
               is inherited.  If $3 is "final", then bye will cause SAM
               to exit.  Use "-" for $2 if needed to define $3.  bound
               will display a menu unless sh_flag is set.

     bye       Causes SAM to leave current menu and return to the
               previous.

    menu       If $1 is blank, displays local and global menus
               otherwise displays these menus for $1.

This menu is hosted by...

SAM Kernel and Application

Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008, 2010, 2011, 2012
Joseph Rosevear.  SAM comes with ABSOLUTELY NO WARRANTY; for details
type

   love; about; warnty; bye; bye

This is free software, and you are welcome to redistribute it under
certain conditions; for details type

   love; about; redist; bye; bye
^^^

You can see by examining the menu that it has two parts called "local"
and "global".  The global part describes commands that are intended to
be "globally" available.  The term "global" here is mine.  It means
that the commands are always available for any choice of local menu.

The first line

   /tmp

shows the directory that is now local.  This tells you that "/tmp" has
been added to the PATH variable and hash has been run so that the
commands of /tmp are now available.  We didn't put any commands in
/tmp.  I suggest that you try putting a command or two there if you are
unfamiliar with the use of hash and the PATH variable.

Here is what I get when I look at the PATH variable ("echo $PATH"):

   /opt/SAM/sam:/tmp/temp1:/opt/SAM/tool:/usr/local/bin:/usr/bin:/bin:/usr/games:/usr/lib/java/bin:/usr/lib/kde4/libexec:/usr/lib/qt/bin:/usr/share/texmf/bin:.:/home/joe/sam-start

If you look at this long line you will see that it contains some new
elements that weren't in PATH before you ran SAM.  I'll name describe
them here:

   /opt/SAM/sam         This is the sam kernel.  These commands are
                        needed by SAM.

   /tmp/temp1           This is the location of the temporary directory
                        ($sam_temp_dir) currently in use by SAM.

   /opt/SAM/tool        This is the location of SAM's tool package,
                        an optional package that adds commands to the
                        global menu.

   /home/joe/sam-start  This will be a little different for you.  It
                        will name sam-start in your home directory
                        (even if it doesn't exist).

The rest of the menu describes what is intended to be the commands that
are available locally and globally through SAM.  The commands that are
intended to be available locally are in file /tmp/menu.dat, because
/tmp is the local directory.

The commands that are intended to be available globally are described
in $sam/menu.dat, $sam_tool/menu.dat, plus the "exit" command which is
actually a built-in shell command.

After the above information you are still missing something about
menus.  "How do I format a menu correctly and how do I make my menu
come up when SAM is run?"  I can address both of these by referring
you to the tips directory

   /opt/SAM/tips

It contains an example sam-start directory.  You don't have to have a
sam-start directory in your home directory, but it is meant to be a
convenient way to make a menu that comes up automatically when SAM is
run.  If you want one, you can copy the sam-start in tips to your home
directory, then customize it to meet your needs.

The sam-start directory can contain any commands that you wish to put
in it.  These can be scripts, compiled code, or even function
definitions.  Give your function definition files a name that ends in
".sam" and they will be automatically made available at the appropriate
time just like an ordinary commands.  (You will need also to include
the line "#OK SAM" as the first line of the function definition.)

You can use the menu.dat file in /opt/SAM/tips as an example or just
use (handy) mzit command which is in the sam-tool package of this
distribution.

8.  Special variables

These variables can be used to control the behavior of SAM.  Set them
anyplace and anytime:

export sam_batch=batch

  Exporting sam_batch with value of batch (or anything) will cause SAM
  to be run in a batch mode.  In this mode it will not give you
  interactive behavior.  Sometimes interrupting a shell script results
  in an interactive shell opening at the point where the script
  stopped.  Often this is not desired.  Use this variable to prevent
  this behavior.

sh_flag=sh

   Export this or just set it.  When it has a value not equal to "" it
   prevents the automatic displaying of menus by SAM.  Menus can still
   be dispalyed manually by the "menu" command.


These variables also control the behavior of SAM.  Normally they should
be set and exported from inside $sam_env:

export sam_menu=<alternate menu executable>

   You would export this to change the behavior of
   $sam_distro/sam/menu, the script which displays SAM's menus.

export sam_message=<executable that you wish to run upon exiting SAM>

   Normally you export this to change the message that SAM displays
   upon exiting.  You would then set sam_message to the path of an
   executable that displays a message.

   The default is to use SAM's prepared message.  This variable is used
   by $sam_distro/sam/sam_core.

export sam_view=<alternate menu viewer>

   You would export this to change the viewer which is used by
   $sam_distro/sam/menu to display menus.

   The default viewer is "less".

There are other variables that are important to SAM but are normally
dealt with by your "~/.bash_profile".  Read about them in /tips/README
in this package ($sam_distro/tips/README).


9.  There is a nuisance that you might encounter.  This nuisance
happens when files in $sam_temp_dir (which points to the current temp
for SAM) gets files in it that cannot be written to.  Say for example
that you have a temp dir at ~/temp1, but you get a file in it that
belongs to root.

When this happens you will need to change to root, go to ~/temp1 (or
temp2, etc) and change the ownership of the files back to the user (not
root). Or you can leave SAM, clean out the $sam_temp_dir's, and try
again.


10.  A diagram of files and dirs in /var/opt/SAM

View with a monospace font, or refer to the notes below the diagram.


var/         
   opt/      _This <user> is normally $sam_temp_base
      SAM/__|______________
         <user>/___________|__ made by rc.SAM
            scratch/_______|
            temp1/___________
            temp2/___________|
            temp3/___________|__ made by /opt/SAM/sam/sam_core
            temp4/___________|
            temp5/___________|
              |
              |_These, temp<n>, are called $sam_temp_dir

Notes:

SAM, <user>, and scratch are made by rc.SAM.

temp1, temp2, etc. are made by /opt/SAM/sam/sam_core.

<user> (/var/opt/SAM/<user>) is normally $sam_temp_base, although you
can set sam_temp_base to other values.

temp<n> are know as $sam_temp_dir.


11.  Shells used


SAM uses #!/bin/sh in all scripts except in this case:

   Scripts that are to be sourced have no line beginning "#!".

I spent some time trying out SAM in Ubuntu.  In Ubuntu /bin/sh is a
link to dash.  SAM should work OK in Ubuntu if you first change that
link to point instead to the (traditional) bash.  Also you may need to
have a real root account.  There is a change you can make in Ubuntu to
do this.  I recommend it.  (Do "sudo passwd root" to get a real root. 
If you change your mind do "sudo passwd -l root" to lock root again.)

One script (sam_core) in the kernel package has code that opens
additional shells.  This is done using "/bin/bash".  I chose
"/bin/bash" over "/bin/sh", because I wanted to use the --rcfile
option.  Using this option let me write better code, so I did it.  This
works in Ubuntu, but functionality in Ubuntu was not the reason for the
choice.
