path: root/libtecla-1.6.3/INSTALL

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 makefile variables which can be
overriden when you run make.

Configure script options:

  If the users of your package won't benefit from having access to the
  tecla man pages, you can shorten the length of time taken to run the
  configure script by telling this script not to preprocess the man
  pages. This is done as follows.

    ./configure --without-man-pages

  Note that this option also causes the makefile man-page installation
  targets to do nothing.

  Similarly, if you don't want your users to have access to the
  filesystem while they are editing input lines using gl_get_line(),
  then use the following configuration argument.

    ./configure --without-file-actions

  This will completely remove the "expand-filename", "read-from-file",
  "read-init-files", and "list-glob" action functions. It will also
  arrange that the default behavior of actions such as "complete-word"
  and "list-or-eof" be changed to show no completions, instead of the
  normal default of showing filename completions.

  If you are using a system that doesn't have a file-system, such as an
  embedded system, then libtecla can be built with all code that
  accesses the filesystem removed. This will make the library a bit
  smaller, and potentially avoid running into problems of missing system
  functions related to file-system access. This is done with the
  following configuration option.

    ./configure --without-file-system

  Beware that this not only prevents the user from accessing the
  filesystem while editing an input line in gl_get_line(), but also
  removes all public file-related functions, such as the pathname
  expansion module. When using gl_get_line() in this configuration,
  the functions that load and save history from and to files, are
  stubs that report an error if called upon to read files. The
  gl_configure_getline() function can still be called upon to
  configure gl_get_line() via its app_string argument, but passing it
  a filename in either the app_file or user_file arguments will result
  in an error being reported.

Now lets say that you have your own configuration script in the parent
directory of the libtecla top-level directory, and that you don't want
tecla's man pages to be generated. In your configuration script, you
would first need to have a line similar to the following:

  (cd libtecla; ./configure --without-man-pages)

Now, from your makefile or whatever script you use to build your
application, you would need to make the tecla library. Assuming that
your makefile or build script is in the parent directory of the
libtecla distribution, then the following line tells make to just
build the non-reentrant, static version of the tecla library, and then
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)

In this statement the LIBDIR=../lib component means that on installing
the library, the make command should place the library 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)