Installing Tela                             Last modified 20.9.1995
---------------                             For version >= 1.23

Installing Tela may take a while since it needs several other components
in order to be fully functional. All components are public domain or
under GNU General Public License.

                   --------------------
                    QUICK INSTRUCTIONS
                   --------------------

1. Determine what other package are needed and install them.
   You need: GNU Readline library version 2.0 or later,
   HDF library (libdf.a plus include files) version 3.1r5
   or 4.0b1, BLAS library, LAPACK library, PlotMTV
   version 1.4.1t or later. In addition you may find it
   convenient to have the bison++ and flex++ parser generators
   installed. For dynamic linking you may use the Elf DSO stuff
   (autoconfigured) or the DLD library (libdld.a, dld.h), which
   works fine at least in Linux, or leave dynamic linking out.

   These packages can be found in many places, but at least
   in ftp.funet.fi:pub/sci/math/tela/needed/.
   
   (You no longer need FFTPACK because it is now all in one
    C source file.)

   Notice that all the libraries and include files should
   be in public places, e.g. /usr/local/lib and /usr/local/include,
   otherwise users can't run the "telakka" script later on.

2. Run "./configure".

3. Possibly edit "makeinc". Check at least all "unknown".

4. Run "make", "make install" and possibly "make installdocs".


                    -------------------
                     LONG INSTRUCTIONS
                    -------------------

Here's what you need, in addition to the Tela source code.

1. A decent C++ compiler. For example, GNU g++ or AT&T Cfront will do.
   Also IBM and HP native C++ compilers can be used, possibly with very
   minor syntactic fixes in source code.

2. A Fortran (F77) compiler to compile the LAPACK library.
   In absence of a native F77 compiler, you can use f2c to translate to
   C and then use C compiler (this is the method used in Linux).

3. The bison++ and flex++ parser and lexical analyser generators.
   These are not absolutely necessary because the generated files
   d.y.c, d.l.c, d.y.h, d.l.h are included in the distribution.
   If you decide that you try to manage without them, you may need
   to type something like 'touch d.?.c d.?.h' if you change some of
   the *.H headers.

4. HDF library. You need the HDF include files and the library,
   libdf.a. Tela has been tested with version 3.1r5 and 4.0b1 of the
   library. Versions 3.2 and 3.3 are known NOT to work. If you use
   3.1r5 you must add -DOLD_HDF_VERSION=1 to DEFS in makeinc when
   compiling files.ct. Some newer I/O functions are not operational
   in this case, e.g. export_netCDF returns warning code. Pros and
   cons:

  3.1r5: + Tela executable size will be smaller
         - Real number data lose precision since they are saved as 32-bit
           numbers
  4.0b1: - Executable will be larger (approx. 400 kB on Linux)
         + Unidata netCDF files become possible to load, import and export
         + No precision loss occurs if HDFNewMode(1) is called
           before saving

   Notice that there is a small bug in the HDF4.0b1 headers: 'new'
   is used as identifier in hfile.h and vg.h. One fix is to replace
   'new' by e.g. 'isnew' in these two places in the headers (after
   installing them). 4.0b2 should fix this problem.

   You can obtain HDF4.0b1 from ftp.ncsa.uiuc.edu and from mirroring
   sites, e.g. ftp.sunet.se (Europe).

5. BLAS library, all three levels. In the usual configuration you
   need the double precision version, that is routine names
   starting with D and Z (you don't need S and C routines).
   The Tela Treal/Tcomplex types should correspond to the
   BLAS types, and Tint should be equivalent to Fortran INTEGER.
   For optimal performance you should use a platform-specific
   BLAS library supplied with the OS, only if none is available
   should you resort to self-compiled Fortran routines.
   Usually the "configure" script is able to locate the system's
   BLAS library.

6. LAPACK library. You can just compile it with your Fortran
   compiler, or f2c. Optimization is not so important here,
   though you would normally turn it on, because the dirty
   work is done by the BLAS routines in most cases.
   Normally you need on the D and Z versions, as with BLAS.
   By the way, if you really want to change Treal to mean
   something else than 'double', in which case you probably
   also need S and C versions, be sure to change also header
   file lapack.H. Not recommended.
   If you don't want to install the full Lapack library,
   you can use the reduced set of routines that can be found
   near the Tela source code (lapack-1.1-sel-src.tar.gz).
   On some systems (SGI, Cray) the LAPACK library is bundled
   in the operating system. The "configure" script knows about this.

7. The PlotMTV program should be installed somewhere in your
   PATH to display your graphics. The t-series PlotMTV versions
   (>=1.4.1t) are Tela-compatible with some enhancements over the
   plain PlotMTV. The t-series PlotMTV should be completely
   compatible with the plain version, so you should upgrade.
   If you don't upgrade you will not be able to use realtime
   graphics (see help figure). The environment variable TELA_PLOTMTV
   may be set to the name of the wanted PlotMTV executable that
   you want to use with Tela. PlotMTV was created by Kenny Toh.

8. You need the GNU readline library. Probably almost any version
   will do, but I have used 2.0. If you cannot get it work (like
   it may happen on Cray UNICOS8.0) you can compile noreadline.c and
   use noreadline.o in place of libreadline.a. You still have to
   point Tela to the proper Readline include files, though.

OK, after you have all the components, you are ready to make Tela.
Do the following:

   The Tela Makefile uses the make program's include mechanism to
   include a preample file called makeinc. Makeinc contains some
   system dependent definitions, and it is created automatically
   by the "configure" script. The script has been generated with
   the GNU autoconf.

0) Decide whether you want to keep your object files in the main
   source directory or not. In the former case just type ./configure
   and make. In the latter case, do the following (example on
   Linux architecture):

        mkdir linux-bin
        cd linux-bin
        ln -s ../Makefile .

   But doing this requires that your make program understands
   the VPATH feature correctly. GNU gmake does.
   Having a separate object code directory is useful if you want
   to maintain several binary versions with e.g. different optimization
   levels or architectures from the same source tree.

   The SGI Irix v.5.0,1,2 make has severe bugs. Use gmake.

1) Type ./configure to create makeinc, or ../configure if you
   are running from arch-bin. If the ./configure script
   finds both GCC and cc/CC on your system, it asks you which one
   you want to use. It also asks for installation directory
   (both architecture independent and dependent). These can be changed
   after configure has completed by editing "makeinc".

2) Edit "makeinc". At minimum you must edit the points where the
   "unknown" string appears. Usually these are libraries that you
   have not yet installed, or have installed in places where configure
   could not find them.

	- Set paths to LAPACK and FFTPACK libraries (you just compiled
      these didn't you)
	- Set path to your GNU readline library and the termcap library.
      If these are in the standard directories, -lreadline -ltermcap
      will do. The GNU readline include file is referenced as
      #include "readline/chardefs.h". So you have to place them
      in directory 'readline'. Set READLINEINCLUDE to point to the
      parent dir of the 'readline' directory. If your 'readline' dir
      is in your main Tela dir, READLINEINCLUDE may be empty.
      To avoid problems, you might use the version of Readline that
      is distributed with Tela (directory readline-related).
	- Set CFLAGS to wanted C optimization/debug etc. flags
	- Set UNROLL_FLAGS to additional optimization flags used when
      compiling objarithm.C. This module contains the basic low level
      loops that benefit from unrolling on most machines. If your
      compiler can do unrolling reliably, you can set an unroll flag
      in force here, if you don't mind that your Tela executable
      may become slightly bigger. Also other loop-related flags,
      such as forced vectorization or parallelization may be useful.
      All loops in objarithm.C can be safely vectorized, so in UNICOS
      you might set UNROLL_FLAGS = -hivdep.
	- Set FLIBS to the relevant Fortran libraries. If you are using
      f2c, FLIBS=-lf2c will do. Otherwise, (if you are using the
      system supplied f77), you probably have to set FLIBS to contain
      at least -lF77 -lI77 and -lisam on some systems.
      These are the Fortran libraries referenced by the LAPACK and BLAS
      libraries.
	- Set HDFLIBS to point to your libdf.a.
	- Set HDFINCLUDE to point to the directory where the HDF include
      files can be found. Also set a relevant -Darchitecture flag as
      required by HDF.
	- Set BLASLIB to point to your BLAS library. If you compiled BLAS
      yourself, then you already know where it is. Many systems have
      BLAS as a system supplied library; for these BLASLIB=-lblas will
      often do, but you have to check.

3) Type make. This will make libtela.a and the executable 'tela'.
   If you run into problems, go back to item (2) above and try again!
   It will also produce the "telakka" script (TeLa Kernel Konstruction
   Accessory), but this "telakka" is not the final version that users
   can use.

4) Type "make install". This will install all the necessary files
   usually under /usr/local/lib/tela. This will also generate and
   install the final version of "telakka".

5) Create symlinks in /usr/local/bin or whatever your favorite for
   local binaries is: ln -s /usr/local/lib/tela/ARCH/tela /usr/local/bin/tela,
   ln -s /usr/local/lib/tela/ARCH/telakka /usr/local/bin/telakka,
   where ARCH is the architecture-specific directory given to configure.
   You need to do this only once, of course. Or just copy the executables,
   but then you have to copy again if you upgrade Tela.

7) Each user can set TELAPATH if needed. If TELAPATH starts with
   a colon (:), its contents will be appended to the standard path.
   For instance, if a user has her own Tela files in $HOME/tela,
   she might say 'setenv TELAPATH :${HOME}/tela' in her .login.
   The standard places are then searched before $HOME/tela.
   The environment variable TELAPATH_SYSTEM is read before TELAPATH
   and processed similarly. It provides for additional freedom in
   configuring and placing Tela. The following practice is recommended
   (for the system manager):

   a) After first installation, let TELAPATH_SYSTEM be undefined.
      Each user should set his own TELAPATH, if necessary, and start
      it with a colon.
   b) If you want to give all users access to a common directory
      containing some additional Tela files, set TELAPATH_SYSTEM
      globally. Again, it should start with a colon not to override
      the compiled-in default.
   c) If you want to move Tela to a different location, you must
      set TELAPATH_SYSTEM globally. This time it should not start with
      a colon, because you want to override the compiled-in default.

8) Copy docs/tela.1 and docs/telakka.1 (the man pages) to the approriate
   places, usually /usr/local/man/man1.

IF YOUR make DOESN'T SUPPORT include:
-------------------------------------
Then use a make program that does, such as GNU make.
Or, include makeinc manually after typing ./configure.
Again, usually you have to do this only once.


CHANGES THAT HAVE TO BE MADE ON SOME SPECIFIC SYSTEMS
-----------------------------------------------------
*** Notice. Partly the information here is rather old!

SunOS 4.1.3 with g++-2.5.8.
--------------------------

The port was finally successful, but some quite bizarre
things showed up. Fortunately these were not related to
the Tela C++ code itself but to some auxiliary things
such as plotmtv and readline library.

The standard flexskel.cc includes osfnc.h without
including sys/time.h. Insert #include <sys/time.h> there
if the compiler complains.
Be careful to specify the correct FLIBS (must be compatible
with f77 version you are using).
When including HDF headers, we had to give -DCONVEX in
addition to -DSUN. This is a dirty workaround for a problem
with char*malloc <--> void*malloc.
When compiling plotmtv the linker complained about 'mcount'
not defined. No idea where this comes from. A dirty hack:
write a file dummy_mcount.c with the contents:
#include <stdio.h>
int mcount() { return 0;}
compile it with cc -S to obtain dummy_mcount.s. Edit the
assembly file and change _mcount to mcount. Compile with
cc -c dummy_mcount.s to obtain dummy_mcount.o. Include this
file in the link, eg. put it after '-lm'.

Convex 10.2.188 using system's own cc and CC (AT&T 2.1 based)
-------------------------------------------------------------
- See grep CONVEX *.C *.H *.ct *.c *.h
- Need to insert 'char*alloca(int)' in d.y.c by hand
- Needed to use newest (3.70) version of GNU make in order
  to get dependencies right at all! System's own make or
  older gmake refused to work properly.
- Had to remove definition of struct DFdi from HDF header
  dfsd.h. (Version 3.2 of HDF), otherwise the compiler complained
  about 'class declared twice'.

AIX 2.3 31.10.1994 (rutja.oulu.fi), Tela-1.12
---------------------------------------------

- Had to edit d.y.c to change #include <alloca.h> to #include <malloc.h>
- Had to modify the C++ sources in few places; see grep _AIX *.C *.H.
  The xlC compiler's idea of CONSTness seems to differ from other civilized compilers.
- Had to use version 2.0 of Readline library. Installing it was extremely straightforward.
- BLAS routines are in libessl.a, but LAPACK must be compiled, which took some time (!)
  Used command like xlf -c -O -qextname *.f in lapack-1.1-sel-src. On files dgesvd.f and zgesvd.f xlf
  warned that the routine was not properly optimized ==> used xlf -c -O -qextname -qmaxmem=10000 {z,d}gesvd.f
  for these two source files.
- Also remember to use -qextname and -qautodbl=dbl when compiling libfftpack:
  xlf -c -O -qextname -qautodbl=dbl *.f
- To link statically under AIX: -bnso -bI:/lib/syscalls.exp -lCns
- xlC failed to compile fftpack.C with -O3 (resulted internal compiler error). -O2 worked.