Installing APLX for Linux

PREREQUISITES

APLX for Linux requires recent versions of the Linux kernel and GLIBC
shared libraries as well as the LIBJPEG shared library. Please see the
"pre_install.txt" document to see how to check which versions you have
on your system, and instructions for updating these components if necessary.
Most recent versions of Linux already satisfy these prerequisites.

MicroAPL has tested APLX for Linux on the following distributions (applying
where necessary the upgrades described in "pre_install.txt"):

Debian 3.0 
Fedora Core 1 
Fedora Core 2 
Fedora Core 4 
Fedora Core 5 
Fedora Core 5 x86_64 (64-bit OS) 
Mandrake 9.0 
Mandrake 9.1 
Mandriva 2006 
RedHat 6.2 
RedHat 7.0 
RedHat 7.3 
RedHat 8.x 
RedHat 9.0 
SuSE 8.1 
SuSE 9.1 
Ubuntu 6.10 
Ubuntu 6.10 AMD64 (64-bit OS) [requires Ubuntu 32-bit libraries, package ia32-libs]   
    
Users of APLX on a wide variety of other Linux distributions have 
reported no problems.


INSTALLING AS USER OR ROOT?

In order to display and print the special APL symbols, the APLX fonts 
included on the CD must be installed on your system. Super-user privileges
are normally required to install X-windows fonts in Linux.

Installing as root:

This is the recommended option, as the APLX fonts will be installed
automatically and APLX for Linux will be available for all users
of the system. By default, APLX is installed to "/usr/local/" when
installing as root.

Installing as a normal user:

It is also possible to install the APLX application as a normal user,
however, the APLX fonts will still need to be installed by the system
administrator. When installing as a normal user "xxx", APLX is installed
to "/home/xxx/aplx" by default and will not be available to other users
of the system. To install APLX as a normal user, follow the installation
instructions below then contact your system administrator to install
the fonts. APLX will not work correctly until the fonts are properly
installed. The directory "fonts" on the APLX CD includes a script to
install the fonts separately as well as instructions for installing
the fonts manually, if that is preferable.



INSTALLING APLX


1. Log in as root or as a normal user

   If you log in directly into X-windows as the installing user, the
   APLX installer will use a "graphical mode" X-windows dialog box to
   allow you to configure the installation, otherwise it will fall back
   to "text mode", where the installation is configured by a series of
   prompts in the console. This occurs if you log in to X-windows as one
   user, then use "su" to switch users or become root within a terminal.
   

2. Open an X-windows shell window


3. If your copy of APLX came on CD, insert the APLX CD in your CD-ROM 
   drive and mount the CD file system

       mount /mnt/cdrom
   
   CD file systems are normally mounted at "/mnt/cdrom" in Linux. Substitute
   the appropriate mount point if your system is configured differently.
   Depending on your configuration, the CD file system might be automatically
   mounted when the CD is inserted.


4. Change directory to the CD mount point, or the directory where you saved
   the downloaded software.


5. Run the APLX installer

       sh setup.sh


6. Follow the on-screen instructions to install APLX

   The "Install Path" you choose determines where the APLX application, help,
   and other APLX files are installed. The installer creates a symbolic link
   to "startaplx" in the "Link Path" that you specify. This should be
   somewhere in the normal executable search path such as "/usr/local/bin/"
   or "/home/xxx/bin/".

   
7. When the installation is complete, inspect the messages in the X-windows
   shell window from which you started the installer. 

   Please note that if you installed APLX as a normal user, an additional
   installation step is required by your system administrator to install
   the APLX fonts. This is described in an earlier section.


8. Restart the system

   Once the APLX fonts are installed, restart the system to make the fonts
   available to X-windows. It is possible to make the fonts available
   without restarting the system, but the method for doing this depends on
   your system configuration. See "fonts/README.txt" in the APLX install
   path for more information.


9. Start APLX to check that the installation was successful

   If you use the GNOME or KDE desktop environments and chose to install
   shortcuts, an icon for APLX will be available in your program menu.
   Otherwise, you can start APLX from a shell window with the "startaplx"
   command.
   
   If you have problems at this stage, please refer to the troubleshooting
   section below.
   

We hope you enjoy using APLX for Linux!




TROUBLESHOOTING

If APLX for Linux has not installed correctly, please look through this
section for a relevant problem description. If you are having some difficulty
not covered below, please contact us for assistance. Contact details are given
at the bottom of this document. If possible, please include the installation
log created by the APLX installer. This is called "aplx_install_log", and
should be in the home directory of the user who installed APLX.


Problems running the installer:


a.  The installer exits with the message:
    "Your system does not meet the minimum system requirements"

    APLX for Linux requires recent versions of certain system components,
    such as the GLIBC shared library. The installer attempts to determine
    which versions are installed before continuing. For complete information
    of these requirements, please see the document "pre_install.txt" on the
    APLX CD.

    If you are satisfied that your system meets the installation
    prerequisites and that the installer is incorrectly detecting older
    versions etc., you can force the installation to proceed by setting an
    environment variable before running the installer:
    
        FORCE_APLX_INSTALL=1 sh setup.sh
  


Problems starting APLX:


b.  "startaplx: command not found"

    As described in installation step 6 above, the APLX installer creates
    a symbolic link to the APLX launcher "startaplx" using the "Link Path"
    you specify during installation. Normally, this link should be created
    somewhere in the normal executable search path, so that the "startaplx"
    command can be used from any directory. If you see the error message
    above, either the link is not in your normal executable search path,
    or a more serious problem has occurred during installation. First check
    that the "startaplx" program exists in the APLX install directory. e.g.
    if you installed to "/opt/aplx/", there should be an executable file
    "/opt/aplx/bin/startaplx". If this does not exist, the installation
    has failed. Please repeat the installation and look for any messages
    in the shell window. If "startaplx" does exist in the APLX installation
    directory, it is simply a problem with your search path. The easiest
    solution is to create a new symbolic link manually somewhere in your
    search path. Display your search path:
    
        echo $PATH
        
    The result should look something like this:
    
        .:/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin:/home/tom/bin
        
    Create a new link
    
        ln -s /opt/aplx/bin/startaplx  /usr/local/bin/startaplx

    "/opt/aplx/bin/startaplx" is the real file you are linking to, and will
    depend on where APLX is installed. "/usr/local/bin/startaplx" is the 
    link you are creating, and should be in a directory that is listed in
    your $PATH.


c.  "Error in loading shared libraries: XXX.so.YYY: cannot open shared object file"

    Most distributions of Linux have all the shared libraries needed to run
    APLX. Some versions have the correct libraries, but do not use the naming
    conventions APLX is expecting. This normally occurs when version numbers
    are included in the name where APLX is not expecting version numbers.
    If you see the error message above, check for files in "/lib" and "/usr/lib"
    which have similar names to the missing file. If the library is present,
    you can easily fix the problem by creating a symbolic link to the existing
    library using the name under which APLX is looking for the library.
    As an example, if APLX is missing "libFOO.so.8", but you find 
    "libFOO.so.8.2.0" in "/usr/lib", you can fix the problem by creating a link
    
        ln -s /usr/lib/libFOO.so.8.2.0 /usr/lib/libFOO.so.8

d.  The operating system reports "Incorrectly built binary which accesses 
    errno, h_errno or _res directly. Needs to be fixed." 
    
    This is a known problem with RedHat 9.0, and we believe it can be ignored.
    

Problems using APLX:


e.  The APLX font is not displaying correctly. APL symbols do not appear
    in the APLX session window or editor windows.

f.  The APLX font does not print correctly. APL symbols do not appear in
    the printed output.

    If APLX starts up correctly, but APL symbols do not display and/or print,
    the APLX fonts have not installed correctly. Before continuing, try
    to restart your system as indicated in installation step 8. If the
    problem occurs after a restart, please see the file "fonts/README.txt"
    in the APLX installation directory.

g.  Typing in APLX produces unexpected letters, digits or symbols.

    i.  Unknown or unsupported keyboard layout

        In order to produce the special APL symbols, APLX modifies the
        behaviour of the keyboard. APLX uses the $LANG environment variable
        to determine your normal keyboard layout. Although $LANG should
        normally always be set, some Linux configurations do not seem to
        do so. To check your current $LANG environment setting:
        
            echo $LANG
        
        If this shows no $LANG value, you should modify your log-in script 
        or the startaplx script to set $LANG to one of the supoorted options.
        (See below).
       

    ii. NUM-LOCK

        In some X-windows keyboard configurations, having NUM-LOCK set
        interferes with the APLX key mapping process. The easiest solution
        is to turn off NUM-LOCK when using APLX. For more information, please
        see the man page for "xmodmap".

h.  When you bring up the keyboard layout window, APLX displays up a warning: 
    "Keyboard layout from the LANG environment variable not recognized. 
     Key positions on the APL keyboard map may not be correct."

    This means that the $LANG environment variable is not set to one of the
    standard strings which APLX recognizes.  These are listed in the
    'README.txt' file in the APLX 'keymaps' directory. If $LANG is not set
    to one of these, you can set it for APLX alone by modifying the
    'startaplx' script in the APLX 'bin' directory.  For example, if you
    are using a US keyboard, $LANG should be set to 'en_US'.  (Some
    versions of Linux including RedHat 9.0 might set it to something
    different, such as 'en_US.utf-8').  You can fix the problem by
    adding the following line to your startaplx script (before aplxlinux
    is invoked):
    
       LANG=en_US;export LANG 

    If you are using a non-US keyboard, substitute one of the other
    language strings described in 'keymaps/README.txt'.  For example, if
    you are using a Swiss German keyboard you would enter:
    
       LANG=de_CH;export LANG
       
i.  APLX starts to run, but apparently crashes randomly with the message:
    "Fatal IO error: client killed"
    
    This arises because of an incompatibility introduced in the Linux
    kernel version 2.4 and later.  In fact, APLX has not crashed but the
    X-Windows subsystem has terminated the X session.  This occurs in 
    RedHat 9.0 and Mandrake 9.1 (and probably in other distributions 
    issued later than around May 2003), if you are running APLX version 
    1.1.7 or earlier. 
    
    APLX versions 1.1.8 and later include a workaround for this problem.

       

UNINSTALLING APLX

To uninstall APLX for Linux, use the uninstall script in the APLX
installation directory. You should uninstall as the same user who performed
the installation.

Please note that the APLX fonts are not uninstalled from the X-windows font
directory. To uninstall the fonts, simply remove the font files:

    rm -f /usr/lib/X11/fonts/misc/aplx*
    rm -f /usr/lib/X11/fonts/Type1/aplx*



      
THE INSTALLER PROGRAM

The APLX for Linux installer uses the open-source "Setup" tool created by
Loki Games. See http://www.lokigames.com/ for more information.




CONTACTING MICROAPL

Visit our website:

    http://www.microapl.co.uk/apl
    
for the latest news and updates.

For support, e-mail us at support@microapl.co.uk
To report bugs or problems, e-mail bugs@microapl.co.uk



