Notes on installing A-Shell/LINUX from downloaded web package   20 Nov 2023
===========================================================================

Overview
--------
The release is packaged as a single single cpio file with a .bin
extension. It can be used for both new installations and updates of
existing installations; the procedure is the same in either case.  An
update will not overwrite existing miame.ini and ersatz.ini files, but
it will update message files, function key translation tables, lit
files, etc.  It will save copies of your old function key translation
tables (using "s" as the last character of the extension) but if you
have concerns about other files you may have customized, see the notes
under step 5 below for customizing the installation.)

The name of the cpio/bin file is ash-version-platform{-arch}.bin where
the format of the version and platform fields are as follows:

   version:   (complete version in dotted notation, e.g. 7.0.1752.0)

   platforms:  
              el7  (RHEL/CentOS 7.x)
              cs7  (CentOS Stream 8)
              el9  (RHEL/CentOS 9.x)
              u20  (Ubuntu 20) 
              d12  (Debian 12; also works for Ubuntu 22)
	      lnx  (Generic Linux) (static linked under CentOS 5)

   arch:
                      (Default is i686)
              -x86_64 (Intel / AMD 64 bit)

Depending on the platform, we may offer 32 bit (i686), 64 bit (x86_64) 
or both. See "Full Install Procedure" below (following the individual 
executable update notes) for details on the full installation.

Individual ashell executable updates
------------------------------------

The most common kind of update is just for the ashell executable.  These
use the same naming convention as for the full packages, except the file
extension will be .tz (extract using tar xvzf). These can typically be
installed while users are running, using the following procedure:

1. Change to the bin (or bin64 for 64 bit) directory and rename the existing
ashell.  For example, if the existing version is 7.0.1752.0, you might 
rename it as follows:

    $ mv ashell ashell_17520

2. Extract the update from the tz file, e.g.

    $ tar xvzf ash-7.0.1752.0-d12-x86_64-upd.tz

3. Finally, use chmod and/or chown to change the ownership and bits
(including the setuid bits) to match the prior file.  

------------------------------------------------------------------------
Full install procedure
------------------------------------------------------------------------

1.  Log in as a non-root user which you want to be the owner of the 
    ashell system. (You may want to first create an 'ashell' user.)
    Then use su to change to root. NOTE: use the -p switch to preserve 
    your original user environment. (Depending on your version of 
    UNIX, it may be -r or --preserve-environment switch - consult the
    su man page.)

2.  Place the .bin file in a convenient temporary location, such as /tmp

3.  Extract the ash_install script from the bin file

	# cd /tmp
	# cpio -iuB ash_install < ash-#.#.###-platform{-arch}.bin

4.  If this is an update, and you are concerned about it overwriting 
    files that you may have customized, then besides making sure you
    have a backup, you may want to check the README.TXT file in the 
    $MIAME/custom subdirectory.  It describes how to activate and 
    customize a pair of special scripts that will be called by the 
    installer before and after the process of copying the new files,
    thus allowing you to perform your own special pre-update and 
    post-update processing.  

	# ./ash_install

5.  Following the instructions, specifying a target directory (typically
    /vm/miame for both the runtime and object paths.)  For the source
    device, specify the same path to the bin file as given on the cpio
    command line. 

6.  If this is a new installation and you didn't install to /vm/miame,
    then you will need to manually edit the <install path>/miame.ini 
    file and replace all occurrences of /vm/miame with the actual target
    path you used.  Also, you will need to create an environment variable:

	MIAME=/vm/miame
	export MIAME
	
    This should point to where you actually installed the software.  You
    may also want to update your PATH environment variable to add 
    the $MIAME/bin (for 32 bit) or $MIAME/bin64 (64 bit) executable 
    directory to your search path.

    Typically setting up the MIAME and PATH environment variables is done
    in your logon profile.  

7.  You can use the # exit command to return to your normal login.


Adding an entry for am62a terminals in the TERMINFO database
------------------------------------------------------------
(This step is performed automatically in the ash_install script
for 5.x and above and thus may be skipped unless you create your
own variation of one of the A-Shell drivers.)

If you are using am62a, am65, or am75 terminals or emulators, you should 
add a TERMINFO definition for them.  To do this, log in (or su) to root
and execute:

	# tic -v /vm/miame/am62a.tis

(Again, replace /vm/miame with the actual directory you installed in.)
Note that a TERMINFO definition is not needed for A-Shell, but will be
handy if you want to run any UNIX utilities outside of A-Shell.  

Make sure when you set up your TERM variable, that you use lower case,
such as am62a, am62c, am65 or am75.

If this operation is not successful, don't worry too much.  Some Linux
utilities (such as vi) may require a valid working TERM definition, but
A-Shell itself has its own internal drivers for am62a, am62c, am65, and
am75, wyse50, vt220, vt420, and a few others; as long as your TERM 
definition matches one of those, it will work fine.


Launching A-Shell
-----------------

Launch A-Shell with a command such as:

	$ ashell
or
	$ <path>/ashell

The first format assumes that <path> (to the ashell executable) has
been added to the PATH. Both forms assume you've defined the MIAME 
environment variable.

Additional Documentation
------------------------
Please refer to the A-Shell User's Guide (available on the Download
page at http://www.microsabio.com) for additional details on configuring
A-Shell.  Also look in the doc subdirectory (e.g. /vm/miame/doc) for
readme.txt, which contains some useful pointers are getting started.

Troubleshooting Notes
---------------------
- Running 32 bit A-Shell on a 64 bit machines: For this you need to 
have 32 bit support enabled in the OS, and a complete set of 32 bit
packages installed. 
  
- A-Shell links to the PCRE (Perl Compatible Regular Expressions) library.
If not installed, you'll get a complaint about inability to link to
libpcre.so.3. Check that the package is installed:
  Debian/Ubuntu:  $ apt list --installed | grep pcre
  RHEL/CentOS:    $ rpm -aq | grep pcre

If installed but you still get the error, you may need to manually create
a link named libpcre.so.3 which points to the actual library. For example,
in the Debian 12 installation, the installed library is actually
/usr/lib/x86_64-linux-gnu/libpcre.so.3.13.3.  This is still compatible with
the version ashell is expecting, so you can create a soft link via:

    $ sudo ln -s /usr/lib/x86_64-linux-gnu/libpcre3.so.3.13.3 \
         /usr/lib/x86_64-linux-gnu/libpcre3.so.3

- Libraries packaged with A-Shell: A-Shell is typically distributed with
some auxiliary libraries stored along with the ashell executable in the
bin or bin64 directory and typically using a similar naming convention
to that for the ashell install packages. For example:

    libashnet.so.1.14.190-e12-x86_64
    libxl.so.4.2.0-x86_64
    libashtls.so.1.3.217-d12-x86_64
    libashodbc.so.1.4.122-d12-x86_64

As with most other Linux libraries, there needs to be a link with the 
.so.x extension (x is 1 for all of the current A-Shell libraries) in 
the default system library search path which links to the actual library
in the A-Shell bin or bin64 executable directory. For example, under
Ubuntu 20, you should have a link similar to the following for the 
libashnet library:

     /usr/lib/libashnet.so.1 -> /vm/miame/bin64/libashnet.so.1.14.190-u20-x86_64

- System library directory: Depending on the platform the default system
library location may vary, from /usr/lib/x86_64-linux-gnu to /usr/lib to
/usr/lib64. 

- Checking for executable and library dependencies: Use the ldd utility on
the ashell executable or library, for example:

     $ ldd ashell
        linux-vdso.so.1 (0x00007fffd9dc4000)
        libtinfo.so.6 => /lib/x86_64-linux-gnu/libtinfo.so.6 (0x00007f787fa5f000)
        libpcre.so.3 => /lib/x86_64-linux-gnu/libpcre.so.3 (0x00007f787f9ec000)
        libdl.so.2 => /lib/x86_64-linux-gnu/libdl.so.2 (0x00007f787f9e6000)
        libstdc++.so.6 => /lib/x86_64-linux-gnu/libstdc++.so.6 (0x00007f787f804000)
        libm.so.6 => /lib/x86_64-linux-gnu/libm.so.6 (0x00007f787f6b5000)
        libgcc_s.so.1 => /lib/x86_64-linux-gnu/libgcc_s.so.1 (0x00007f787f69a000)
        libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x00007f787f4a6000)
        libpthread.so.0 => /lib/x86_64-linux-gnu/libpthread.so.0 (0x00007f787f483000)
        /lib64/ld-linux-x86-64.so.2 (0x00007f787fca7000)

Any missing dependencies will be noted with a "not found" error message, from
which you can hopefully identify the missing package and install it.