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)