diff options
Diffstat (limited to 'libtecla-1.6.3/INSTALL')
| -rw-r--r-- | libtecla-1.6.3/INSTALL | 213 |
1 files changed, 213 insertions, 0 deletions
diff --git a/libtecla-1.6.3/INSTALL b/libtecla-1.6.3/INSTALL new file mode 100644 index 0000000..14fc62d --- /dev/null +++ b/libtecla-1.6.3/INSTALL @@ -0,0 +1,213 @@ +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) |