****************************************************************
*                 Khoros 1.05 for Linux                        *
****************************************************************

Wolfram Gloger
wmglo@dent.med.uni-muenchen.de
Feb 14 1993.

WOLFRAM GLOGER DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
AND FITNESS.  IN NO EVENT SHALL WOLFRAM GLOGER BE LIABLE FOR ANY
SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY OTHER DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER
IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
THIS SOFTWARE.

For the Khoros copyright, see file COPYRIGHT.Khoros.

The source code patches in "patch.Linux" are copyright (C) 1994
W. Gloger and may be redistributed and/or modified under the
terms of the GNU General Public License as published by the Free
Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
USA.


I. REQUIREMENTS

To compile the complete Khoros system, you need:

0. Khoros 1.0, patchlevel 5 (source distribution)
1. Linux 0.99.14 or higher
2. XFree86 2.0
3. gcc 2.4, libc 4.5, flex 2.3, GNU bison (or BSD yacc)
4. f2c Fortran to C Converter, version "Feb 1993"
   (not essential, see section III)
5. CShell (or TCShell with an appropriate symlink)
6. The Linux DLL tools 2.10 (if you want to compile the
   shared libraries)

Earlier or later versions, of course, may also work.  Khoros is
available, for example, from ftp.eece.unm.edu, but also from
many other ftp-sites.  I use TCShell, which is available in
binary form, e.g. from tsx-11.mit.edu in
pub/linux/binaries/usr.bin/tcsh-6.04.tar.gz.

After compilation, disk usage of the khoros directory tree is
about 75MB (!), so you need an extended file system partition
(strongly recommended for the "long" filenames, too).  If the
manuals and/or example data sets are deleted, you can get away
with much less disk space.  The binaries themselves are about
6.2MB (optimized for a 486).


II. INSTALLATION

Please refer to the Khoros manual for a detailed explanation
of the Imake system.  The basic strategy for compilation is this:

0. Unpack the Khoros source packages system.tar.Z, data.tar.Z
 and src.tar.Z, e.g. into /usr/local/khoros.

1. Set some environment variables.  Here are excerpts from my
 shell configuration files as examples:
 ---- ~/.profile ----
 KHOROS_HOME=/usr/local/khoros
 export KHOROS_HOME
 PATH=$KHOROS_HOME/bin:/usr/X386/bin:/usr/TeX/bin:~/bin:$PATH
 LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$KHOROS_HOME/lib
 export LD_LIBRARY_PATH
 ----- ~/.cshrc -----
 setenv KHOROS_HOME /usr/local/khoros
 set path=($KHOROS_HOME/bin $path)
 setenv LD_LIBRARY_PATH $LD_LIBRARY_PATH\:$KHOROS_HOME/lib
 --------------------
 PLEASE NOTE:
 Having .../khoros/bin BEFORE /usr/X386/bin in the path can be
 important, see section III.

2. There are several possibilities to start the compilation:
 * (The recommended way :-)
  Run the "install.Linux" shell script from the directory
  that contains "patch.Linux" and "jump.tar" (it should also
  contain the file you are reading now, README.Linux).
  Answer 'Y' to apply the patches to the source tree.
  Watch out that there are no "*.rej" files produced from "patch" !
  Probably you also want to use the "f77" shell script that
  I provide as a replacement for a Fortran compiler.
  (You still need f2c, however.)

 * Alternatively, you could apply my patches by hand (see sec. III),
  untar the "jump.tar" DLL configuration files in KHOROS_HOME,
  and then try to run the original "installit" in the
  KHOROS_HOME/src directory.
  Use the default parameters for the directories if possible.
  WHEN YOU RUN "installit" FOR THE FIRST TIME, ENTER
        -DSYSV -DSYSV386
  FOR THE BOOTSTRAPFLAGS, AS SUGGESTED FOR i386/486 MACHINES,
  BUT *WITHOUT* THE -DUSG, WHICH IS ALSO SUGGESTED.

 * You could also create .../khoros/bin and .../khoros/lib
  by hand and then run in KHOROS_HOME/src:
    make BOOTSTRAPCFLAGS="-DSYSV -DSYSV386" World >& make.World &

 The compiling progress can always be seen with:
 tail -f $KHOROS_HOME/src/make.World
 Please make sure the bootstrap programs, including "makedepend",
 compile correctly, since they are required to produce correct
 Makefiles.  The heap of compiler warnings is due to the
 "traditional" programming style of the Khoros source distribution,
 and should be ignored.
 Compilation of the complete system takes around 3 hours,
 so be patient.

3. *** What if something goes wrong ??? ***
 The reason is most probably that your system configuration is
 different from mine.
 For adaption to your local setup, have a look at the Linux
 configuration file, repos/config/imake_conf/linux.cf.
 Things that you should check include:
 * If you have an older kernel version than listed at the top of
   the file, please adjust "OSPatchLevel" accordingly.
   It is used later.
 * There has to be an executable /lib/cpp.  The easiest way
   to get that right is probably a symlink like
     ln -s /usr/lib/gcc-lib/i[34]86-linux/X.Y.Z/cpp /lib/cpp
   (depending on the version and path of the gcc you are using).
 * You may also need the symlink:
   /usr/include/X11 -> /usr/X386/include/X11
 * You may want to add "-m486" to DefaultCDebugFlags and
   LibraryCDebugFlags.
 * For kernel versions 0.99.10 and above, shared memory transport
   is now enabled by default.  _BUT_ you also need libc >4.4 for
   this.  In case you don't have it, just set UseSharedMem to NO.
   (Shared memory transport is not at all vital.)
 * If you don't want to use the Fortran code (only a few parts
   of Khoros need it), or you don't have f2c, then set
   HaveFortran to NO.
 * If you want to use f2c, you must have a shell script "f77"
   in your path, which behaves just like a real Fortran compiler.
   Also make sure you have the library libf2c.[s]a.
   By default, it is searched in /usr/lib.
   For old versions of f2c, see also section IV.
 * To use BSD yacc rather than GNU bison, change the definition
   of YaccCmd in linux.cf.
 * If you are using flex 2.3, and you don't have libfl.a,
   you can remove "-lfl" from the SysLibs.  But version 2.4
   needs it !
 * To avoid makedepend warnings, set the GCC_INC_DIR definition
   in the bootstrap flags according to your version of gcc.
 * If you don't have the DLL tools, just set HaveSharedLibraries
   to NO.  No shared libraries will be created, but the resulting
   binaries in .../khoros/bin will need more than 30MB (!).

4. After compilation is complete, you should also copy or
   merge (in case you already have a .Xdefaults file)
   /usr/local/khoros/dotfiles/Xdefaults to your home
   directory's .Xdefaults file.  Otherwise you may get funny
   colors or see nothing much in your workspaces...


III. CHANGES IN THE SOURCE FILES

All changes are based on the Khoros source distribution,
version 1.0, patchlevel 5 (Mar 1992).
Paths are relative to the Khoros home directory
(e.g. /usr/local/khoros).
To apply the changes by hand, cd to this home directory and do
"patch -p0 < linux/patch.Linux" (change this if you didn't untar
in the Khoros home directory) and "tar xvf linux/jump.tar".

Here is a brief summary of the changes:

1. Include files.
 include/file_formats/tiffcompat.h,
 include/vdefines.h, vsignal.h, xvparser.h:
  Inserted __linux__ macros, removed i386 where appropriate.
 Many include/*.h:
  Declared global variables "extern", moved their definition
  into a single .../Lib/..._glob.c source file.

2. Configuration files.
 (a) repos/config/scripts/lexyacc_sed.rules:
  Removed lone backslash from comment in the beginning since GNU
  sed can't handle it.  (The bug will hopefully be fixed soon.)
 (b) repos/config/imake_conf/Site.def, Library.def, Khoros.rules,
  Khoros.tmpl, Transport.def, Toolbox.def:
   All were adapted, mostly because the 'KCOM' construction didn't
   work for an ANSI-compliant cpp.
 (c) repos/config/imake_conf/linux.cf,
  repos/config/imake_conf/Lib/linuxLib.rules:
  A new configuration file was created, starting from i386.cf.

3. Bootstrap programs.
 NOTE: It IS necessary to compile and use these programs,
 because the versions supplied with X11 can't deal with very
 long file lists.  SO, please make sure .../khoros/bin comes
 BEFORE .../X386/bin in your path.
 Exception: X11's "imake" utility is sufficient and could
 be substituted for .../khoros/bin/imake.

 src/bootstrap/makedepend/main.c:
  gcc-include-directory changed (for gcc version 2 and above);
  Linux doesn't have SIGBUS or SIGSYS.
 src/bootstrap/imake/imake.c:
  included "-traditional" flag for GNU cpp;
  used lseek() rather than fseek() before read().

4. Linpack library.
 src/public_domain/linpack/Imakefile, cdabs.c:
  Created this file to supply the standard (?) FORTRAN function
  cdabs() which is not present in the f2c library.

5. Lex files (expression parsers etc.).
 Unfortunately, all lex files in Khoros rely heavily on
 features of traditional versions of lex.  They don't work
 with Berkeley-lex or flex.  I decided to adapt them for flex
 and then used the (Berkeley) yacc parser generator.
 GNU bison should work as well.

 src/dspl/poly_lex.l,
 src/file_formats/Lib/matrix_lex.l,
 src/Lib/vexpr/expr_lex.l:
  Adapted for flex.

6. Sockets.
 I included socket support, but it is not extensively tested.
 Turn it off in linux.cf if your kernel is older than 0.99pl14.

7. Xvroutines.
 * src/xvroutines/Lib/xvforms/signal.c:
  Replaced kill(pid, 0) with waitpid(pid, ...), since it
  didn't work properly (Zombies !).
 * src/xvroutines/Lib/xvgraphics/font_3D.c:
  Somehow fgets() does not reach EOF on the last line -
  added break condition.
 * src/xvroutines/cantata/menu.c, util.c:
  Linux doesn't have SIGBUS.

8. Shell scripts.
 src/tools/scripts/check_csh.csh:
  Changed for SYSV ls (with group output).

9. Bug fixes (not specific to Linux).
 src/vipl/feature/vpml/vpml.c,
 src/vipl/Lib/lvextract.c,
 src/vipl/Lib/lvshape.c,
 src/xvroutines/Lib/xvplot/function.c,
 src/xvroutines/Lib/xvplot/gen_util.c,
 src/xvroutines/xprism2/axes2.c,
 src/xvroutines/cantata/glyph.c:
  Fixed bugs.


IV. PROBLEMS

* If you are still using gcc 2.3.3, and get a coredump in
 src/xvroutines/Lib/xvplot, set CFLAGS empty in the Imakefile
 there (overriding configuration file), like this:

--- Imakefile   Fri Mar 20 23:43:38 1992
+++ Imakefile.gcc-2.3.3 Sat Feb  6 10:49:18 1993
@@ -52,6 +52,8 @@
 
 /* INCLUDES = */
 
-/* CDEBUGFLAGS = */
+CDEBUGFLAGS =
+
+LIBCDEBUGFLAGS =
 
 #include <Lib.template>

* If you have an old version of f2c, try replacing "f__cabs" with
 "Cabs" in .../khoros/src/public_domain/linpack/cdabs.c.

* The binaries will *not* work with libXaw3d.  You will just get
 a segmentation fault from all X11-dependent programs.

* *Especially important* is the addition of /usr/local/khoros/lib
  to LD_LIBRARY_PATH, because without it you will only get
    "can't find libkhv.so.1"
  messages from the binaries.  Alternatively, you could add
  /usr/local/khoros/lib to the global list in /etc/ld.so.conf.
  Don't forget to run "ldconfig" to rebuild the ld.so.cache
  (for newer versions of ld.so).

If you find another problem (you certainly will, sooner or later :-)
you can send mail to me, but I don't promise anything.  Of course,
any feedback, suggestions and bug fixes are very welcome.

Good Luck!
Wolfram.
