README revision 75406
126497SacheIntroduction 226497Sache============ 321308Sache 475406SacheThis is the Gnu Readline library, version 4.2. 526497Sache 626497SacheThe Readline library provides a set of functions for use by applications 726497Sachethat allow users to edit command lines as they are typed in. Both 826497SacheEmacs and vi editing modes are available. The Readline library includes 926497Sacheadditional functions to maintain a list of previously-entered command 1026497Sachelines, to recall and perhaps reedit those lines, and perform csh-like 1126497Sachehistory expansion on previous commands. 1226497Sache 1326497SacheThe history facilites are also placed into a separate library, the 1426497SacheHistory library, as part of the build process. The History library 1526497Sachemay be used without Readline in applications which desire its 1626497Sachecapabilities. 1726497Sache 1826497SacheThe Readline library is free software, distributed under the terms of 1926497Sachethe GNU Public License, version 2. For more information, see the file 2026497SacheCOPYING. 2126497Sache 2226497SacheTo build the library, try typing `./configure', then `make'. The 2326497Sacheconfiguration process is automated, so no further intervention should 2426497Sachebe necessary. Readline builds with `gcc' by default if it is 2526497Sacheavailable. If you want to use `cc' instead, type 2626497Sache 2726497Sache CC=cc ./configure 2826497Sache 2926497Sacheif you are using a Bourne-style shell. If you are not, the following 3026497Sachemay work: 3126497Sache 3226497Sache env CC=cc ./configure 3326497Sache 3426497SacheRead the file INSTALL in this directory for more information about how 3526497Sacheto customize and control the build process. 3626497Sache 3747558SacheThe file rlconf.h contains C preprocessor defines that enable and disable 3847558Sachecertain Readline features. 3926497Sache 4075406SacheThe special make target `everything' will build the static and shared 4175406Sachelibraries (if the target platform supports them) and the examples. 4275406Sache 4326497SacheExamples 4426497Sache======== 4526497Sache 4626497SacheThere are several example programs that use Readline features in the 4726497Sacheexamples directory. The `rl' program is of particular interest. It 4826497Sacheis a command-line interface to Readline, suitable for use in shell 4926497Sachescripts in place of `read'. 5026497Sache 5126497SacheShared Libraries 5226497Sache================ 5326497Sache 5426497SacheThere is skeletal support for building shared versions of the 5547558SacheReadline and History libraries. The configure script creates 5647558Sachea Makefile in the `shlib' subdirectory, and typing `make shared' 5747558Sachewill cause shared versions of the Readline and History libraries 5847558Sacheto be built on supported platforms. 5926497Sache 6047558SacheConfigure calls the script support/shobj-conf to test whether or 6147558Sachenot shared library creation is supported and to generate the values 6247558Sacheof variables that are substituted into shlib/Makefile. If you 6347558Sachetry to build shared libraries on an unsupported platform, `make' 6447558Sachewill display a message asking you to update support/shobj-conf for 6547558Sacheyour platform. 6626497Sache 6747558SacheIf you need to update support/shobj-conf, you will need to create 6847558Sachea `stanza' for your operating system and compiler. The script uses 6947558Sachethe value of host_os and ${CC} as determined by configure. For 7075406Sacheinstance, FreeBSD 4.2 using the ELF object file format with any 7175406Sacheversion of gcc is identified as `freebsdelf4.2-gcc*'. 7226497Sache 7347558SacheIn the stanza for your operating system-compiler pair, you will need to 7447558Sachedefine several variables. They are: 7526497Sache 7647558SacheSHOBJ_CC The C compiler used to compile source files into shareable 7747558Sache object files. This is normally set to the value of ${CC} 7847558Sache by configure, and should not need to be changed. 7926497Sache 8047558SacheSHOBJ_CFLAGS Flags to pass to the C compiler ($SHOBJ_CC) to create 8147558Sache position-independent code. If you are using gcc, this 8247558Sache should probably be set to `-fpic'. 8326497Sache 8447558SacheSHOBJ_LD The link editor to be used to create the shared library from 8547558Sache the object files created by $SHOBJ_CC. If you are using 8647558Sache gcc, a value of `gcc' will probably work. 8747558Sache 8847558SacheSHOBJ_LDFLAGS Flags to pass to SHOBJ_LD to enable shared object creation. 8947558Sache If you are using gcc, `-shared' may be all that is necessary. 9047558Sache These should be the flags needed for generic shared object 9147558Sache creation. 9247558Sache 9347558SacheSHLIB_XLDFLAGS Additional flags to pass to SHOBJ_LD for shared library 9447558Sache creation. Many systems use the -R option to the link 9547558Sache editor to embed a path within the library for run-time 9647558Sache library searches. A reasonable value for such systems would 9747558Sache be `-R$(libdir)'. 9847558Sache 9947558SacheSHLIB_LIBS Any additional libraries that shared libraries should be 10047558Sache linked against when they are created. 10147558Sache 10247558SacheSHLIB_LIBSUFF The suffix to add to `libreadline' and `libhistory' when 10347558Sache generating the filename of the shared library. Many systems 10447558Sache use `so'; HP-UX uses `sl'. 10547558Sache 10647558SacheSHLIB_LIBVERSION The string to append to the filename to indicate the version 10747558Sache of the shared library. It should begin with $(SHLIB_LIBSUFF), 10847558Sache and possibly include version information that allows the 10947558Sache run-time loader to load the version of the shared library 11047558Sache appropriate for a particular program. Systems using shared 11147558Sache libraries similar to SunOS 4.x use major and minor library 11247558Sache version numbers; for those systems a value of 11347558Sache `$(SHLIB_LIBSUFF).$(SHLIB_MAJOR)$(SHLIB_MINOR)' is appropriate. 11447558Sache Systems based on System V Release 4 don't use minor version 11547558Sache numbers; use `$(SHLIB_LIBSUFF).$(SHLIB_MAJOR)' on those systems. 11647558Sache Other Unix versions use different schemes. 11747558Sache 11847558SacheSHLIB_STATUS Set this to `supported' when you have defined the other 11947558Sache necessary variables. Make uses this to determine whether 12047558Sache or not shared library creation should be attempted. 12147558Sache 12247558SacheYou should look at the existing stanzas in support/shobj-conf for ideas. 12347558Sache 12447558SacheOnce you have updated support/shobj-conf, re-run configure and type 12547558Sache`make shared'. The shared libraries will be created in the shlib 12647558Sachesubdirectory. 12747558Sache 12847558SacheSince shared libraries are not created on all platforms, `make install' 12947558Sachewill not automatically install the shared libraries. To install them, 13047558Sachechange the current directory to shlib and type `make install'. Running 13147558Sache`make install-shared' from the top-level build directory will also work. 13247558Sache 13326497SacheDocumentation 13426497Sache============= 13526497Sache 13626497SacheThe documentation for the Readline and History libraries appears in the 13726497Sache`doc' subdirectory. There are two texinfo files and a Unix-style manual 13826497Sachepage describing the programming facilities available in the Readline 13926497Sachelibrary. The texinfo files include both user and programmer's manuals. 14026497Sache 14126497SacheReporting Bugs 14226497Sache============== 14326497Sache 14426497SacheBug reports for Readline should be sent to: 14526497Sache 14635486Sache bug-readline@gnu.org 14726497Sache 14826497SacheWhen reporting a bug, please include the following information: 14926497Sache 15075406Sache * the version number and release status of Readline (e.g., 4.2-release) 15126497Sache * the machine and OS that it is running on 15226497Sache * a list of the compilation flags or the contents of `config.h', if 15326497Sache appropriate 15426497Sache * a description of the bug 15526497Sache * a recipe for recreating the bug reliably 15626497Sache * a fix for the bug if you have one! 15726497Sache 15826497SacheIf you would like to contact the Readline maintainer directly, send mail 15935486Sacheto bash-maintainers@gnu.org. 16026497Sache 16135486SacheSince Readline is developed along with bash, the bug-bash@gnu.org mailing 16235486Sachelist (mirrored to the Usenet newsgroup gnu.bash.bug) often contains 16335486SacheReadline bug reports and fixes. 16426497Sache 16526497SacheChet Ramey 16626497Sachechet@po.cwru.edu 167