To compile and optionally install the library, it is first necessary
to create a makefile for your system, by typing:

  ./configure

The Makefile that this generates is designed to install the files of
the library in subdirectories of /usr/local/. If you would prefer to
install them under a different directory, you can type:

  ./configure --prefix /wherever

Where you would replace /wherever with your chosen directory. Other
command-line options are available, and can be listed by typing:

  ./configure --help

Having run the configure script, you are then ready to make the
library. To do this, just type:

  make

What 'make' does depends on whether the configure script knows about
your system. If the configure script doesn't know anything specific
about your system, it will arrange for 'make' to produce the static
tecla library, called libtecla.a, and if possible, the reentrant
version of this called libtecla_r.a. If it does know about your
system, it will also create shared libraries if possible. If you are
on a system that isn't known, and you would like shared libraries to
be compiled, please read the file called PORTING to see how this can
be achieved.

To install the library, its include file and it manual pages, type:

  make install

Note that this will also compile the library if you haven't already
done so.

Having compiled the library, if you wish, you can test it by running
the demo programs. After building the library, you should find two
programs, called demo and demo2, in the current directory.

The first of the demos programs reads input lines from the user, and
writes what was typed back to the screen. While typing a line of
input, you can experiment with line editing, tab completion, history
recall etc.. For details about these line editing features, see the
man page gl_get_line(3). If you haven't installed this yet, you can
see it anyway by typing:

  nroff -man man3/gl_get_line.3 | more

The second demo program, called demo2, demonstrates command-completion
with the UNIX PATH. If you type in a partial command name, and press
TAB, the command name will be completed if possible, and possible
completions will be listed if it is ambiguous. When you then enter the
line, the demo program then prints out the full pathname of the
command that you typed. If you type anything after the command name,
filename completion with the tab key reverts to its default behavior
of completing filenames in the current directory.

COMPILING IN A DIFFERENT DIRECTORY
----------------------------------
If you unpack the distribution in a directory which is visible from
multiple hosts which have different architectures, you have the option
of compiling the library for the different architectures in different
directories. You might for example create a sub-directory for each
architecture, under the top level directory of the distribution. You
would then log in to a host of one of these architectures, cd to the
sub-directory that you created for it, and type:

  ../configure

The configure script then creates a makefile in the current directory
which is designed to build the library, object files, demos etc for
the architecture of the current host, in the current directory, using
the original source code in ../. You then repeat this procedure on
hosts of other architectures.

The compilation directories don't have to be sub-directories of the
top level directory of the distribution. That was just described as an
example. They can be anywhere you like.

Every rule in the makefiles that are generated by the configure
script, cites the paths of the target and source files explicitly, so
this procedure should work on any system, without the need for vpath
makefile support.

EMBEDDING IN OTHER PACKAGE DISTRIBUTIONS
----------------------------------------

If you distribute the library with another package, which has its own
heirarchy and configuration procedures, the following installation
options may be of interest to you. At first glance, the use of a GNU
configure script by the tecla library, may appear to reduce your
options for controlling what gets made, and where it gets installed,
but this isn't the case, because many of the parameters configured by
the configure script are assigned to make variables which can be
overriden when you run make.

For example, lets say that you have your own configuration script in
the parent directory of the libtecla top-level directory. In your
configuration script, you would first need to have the following line:

  (cd libtecla; ./configure)

Now, from your makefile or whatever script you use to build your
application, you would need to make the library. Assuming that your
makefile or build script is in the parent directory of the libtecla
distribution, the following line tells make to just make the
non-reentrant, static version of the tecla library, and to install it
and the tecla include file in sub-directories called lib and include
in your current directory.

  (cd libtecla; make LIBDIR=../lib INCDIR=../include TARGETS=normal TARGET_LIBS="static" install_lib install_inc)

First, the LIBDIR=../lib means that on installing the library, it
should be placed in the directory libtecla/../lib. Similarly INCDIR
tells make where to place the include files. The install_lib and
install_inc targets tell make to install the libraries and the include
file. Because the install_man and install_bin targets have been
omitted in this example, the man pages and programs aren't installed.
If you were to include these additional targets then you could use the
MANDIR and BINDIR variables, respectively to control where they were
installed.

The TARGETS variable is used to specify which of the normal and
reentrant versions of the library are compiled. This can contain one
or both of the words "normal" and "reentrant". If you don't specify
this when you invoke make, the default value generated by the
configure script will be used. Depending on whether reentrant POSIX
functions are available for compilation of the reentrant version, this
will be either "normal" or "normal reentrant".

The TARGET_LIBS variable is used to specify which of the static and
shared libraries are to be built. This can contain one or both of the
words "static" and "shared". If you don't specify this when you invoke
make, the default value generated by the configure script will be
used. Depending on whether the configure script knows how to create
shared libraries on the target system, this will be either "static" or
"static shared". Beware that shared libraries aren't supported on many
systems, so requiring "shared" will limit which systems you can
compile your package on. Also note that unless your package installs
the tecla library in a directory which all users of your program will
have access to, you should only compile the static version.
Instructions for adding shared-library creation rules for new systems
are included in the PORTING file.

The OPT variable can be used to change the default optimization from
the default of "-O" to something else.

The DEMOS variable controls whether the demo programs are built.
Normally this has the value "demos", which tells the makefile to build
the demo programs. Setting it to an empty string stops the demos from
being built.

The PROGRAMS variable is used to specify which programs are to be
built and subsequently installed. All available programs are built by
default. Currently there is only one such program, selected by
specifying the word "enhance". This program uses tecla-enhanced
pseudo-terminals to layer command line editing on top of third party
programs.

The PROGRAMS_R variable serves the same purpose as the PROGRAMS
variable, except that programs listed here are linked with the
reentrant version of the library, and should be specified with a _r
suffix. Currently this variable is empty by default.

Martin Shepherd  (mcs@astro.caltech.edu)
