126497SacheIntroduction 226497Sache============ 321308Sache 4165670SacheThis is the Gnu Readline library, version 5.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 19119610Sachethe [GNU] General Public License, version 2. For more information, see 20119610Sachethe file COPYING. 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 60119610SacheIf `configure' is given the `--enable-shared' option, it will attempt 61119610Sacheto build the shared libraries by default on supported platforms. 62119610Sache 6347558SacheConfigure calls the script support/shobj-conf to test whether or 6447558Sachenot shared library creation is supported and to generate the values 6547558Sacheof variables that are substituted into shlib/Makefile. If you 6647558Sachetry to build shared libraries on an unsupported platform, `make' 6747558Sachewill display a message asking you to update support/shobj-conf for 6847558Sacheyour platform. 6926497Sache 7047558SacheIf you need to update support/shobj-conf, you will need to create 7147558Sachea `stanza' for your operating system and compiler. The script uses 7247558Sachethe value of host_os and ${CC} as determined by configure. For 73119610Sacheinstance, FreeBSD 4.2 with any version of gcc is identified as 74119610Sache`freebsd4.2-gcc*'. 7526497Sache 7647558SacheIn the stanza for your operating system-compiler pair, you will need to 7747558Sachedefine several variables. They are: 7826497Sache 7947558SacheSHOBJ_CC The C compiler used to compile source files into shareable 8047558Sache object files. This is normally set to the value of ${CC} 8147558Sache by configure, and should not need to be changed. 8226497Sache 8347558SacheSHOBJ_CFLAGS Flags to pass to the C compiler ($SHOBJ_CC) to create 8447558Sache position-independent code. If you are using gcc, this 8547558Sache should probably be set to `-fpic'. 8626497Sache 8747558SacheSHOBJ_LD The link editor to be used to create the shared library from 8847558Sache the object files created by $SHOBJ_CC. If you are using 8947558Sache gcc, a value of `gcc' will probably work. 9047558Sache 9147558SacheSHOBJ_LDFLAGS Flags to pass to SHOBJ_LD to enable shared object creation. 9247558Sache If you are using gcc, `-shared' may be all that is necessary. 9347558Sache These should be the flags needed for generic shared object 9447558Sache creation. 9547558Sache 9647558SacheSHLIB_XLDFLAGS Additional flags to pass to SHOBJ_LD for shared library 9747558Sache creation. Many systems use the -R option to the link 9847558Sache editor to embed a path within the library for run-time 9947558Sache library searches. A reasonable value for such systems would 10047558Sache be `-R$(libdir)'. 10147558Sache 10247558SacheSHLIB_LIBS Any additional libraries that shared libraries should be 10347558Sache linked against when they are created. 10447558Sache 105157184SacheSHLIB_LIBPREF The prefix to use when generating the filename of the shared 106157184Sache library. The default is `lib'; Cygwin uses `cyg'. 107157184Sache 10847558SacheSHLIB_LIBSUFF The suffix to add to `libreadline' and `libhistory' when 10947558Sache generating the filename of the shared library. Many systems 11047558Sache use `so'; HP-UX uses `sl'. 11147558Sache 11247558SacheSHLIB_LIBVERSION The string to append to the filename to indicate the version 11347558Sache of the shared library. It should begin with $(SHLIB_LIBSUFF), 11447558Sache and possibly include version information that allows the 11547558Sache run-time loader to load the version of the shared library 11647558Sache appropriate for a particular program. Systems using shared 11747558Sache libraries similar to SunOS 4.x use major and minor library 11847558Sache version numbers; for those systems a value of 11947558Sache `$(SHLIB_LIBSUFF).$(SHLIB_MAJOR)$(SHLIB_MINOR)' is appropriate. 12047558Sache Systems based on System V Release 4 don't use minor version 12147558Sache numbers; use `$(SHLIB_LIBSUFF).$(SHLIB_MAJOR)' on those systems. 12247558Sache Other Unix versions use different schemes. 12347558Sache 124157184SacheSHLIB_DLLVERSION The version number for shared libraries that determines API 125157184Sache compatibility between readline versions and the underlying 126157184Sache system. Used only on Cygwin. Defaults to $SHLIB_MAJOR, but 127157184Sache can be overridden at configuration time by defining DLLVERSION 128157184Sache in the environment. 129157184Sache 130157184SacheSHLIB_DOT The character used to separate the name of the shared library 131157184Sache from the suffix and version information. The default is `.'; 132157184Sache systems like Cygwin which don't separate version information 133157184Sache from the library name should set this to the empty string. 134157184Sache 13547558SacheSHLIB_STATUS Set this to `supported' when you have defined the other 13647558Sache necessary variables. Make uses this to determine whether 13747558Sache or not shared library creation should be attempted. 13847558Sache 13947558SacheYou should look at the existing stanzas in support/shobj-conf for ideas. 14047558Sache 14147558SacheOnce you have updated support/shobj-conf, re-run configure and type 14247558Sache`make shared'. The shared libraries will be created in the shlib 14347558Sachesubdirectory. 14447558Sache 145119610SacheIf shared libraries are created, `make install' will install them. 146119610SacheYou may install only the shared libraries by running `make 147119610Sacheinstall-shared' from the top-level build directory. Running `make 148119610Sacheinstall' in the shlib subdirectory will also work. If you don't want 149119610Sacheto install any created shared libraries, run `make install-static'. 15047558Sache 15126497SacheDocumentation 15226497Sache============= 15326497Sache 154119610SacheThe documentation for the Readline and History libraries appears in 155119610Sachethe `doc' subdirectory. There are three texinfo files and a 156119610SacheUnix-style manual page describing the facilities available in the 157119610SacheReadline library. The texinfo files include both user and 158119610Sacheprogrammer's manuals. HTML versions of the manuals appear in the 159119610Sache`doc' subdirectory as well. 16026497Sache 16126497SacheReporting Bugs 16226497Sache============== 16326497Sache 16426497SacheBug reports for Readline should be sent to: 16526497Sache 16635486Sache bug-readline@gnu.org 16726497Sache 16826497SacheWhen reporting a bug, please include the following information: 16926497Sache 17075406Sache * the version number and release status of Readline (e.g., 4.2-release) 17126497Sache * the machine and OS that it is running on 17226497Sache * a list of the compilation flags or the contents of `config.h', if 17326497Sache appropriate 17426497Sache * a description of the bug 17526497Sache * a recipe for recreating the bug reliably 17626497Sache * a fix for the bug if you have one! 17726497Sache 17826497SacheIf you would like to contact the Readline maintainer directly, send mail 17935486Sacheto bash-maintainers@gnu.org. 18026497Sache 18135486SacheSince Readline is developed along with bash, the bug-bash@gnu.org mailing 18235486Sachelist (mirrored to the Usenet newsgroup gnu.bash.bug) often contains 18335486SacheReadline bug reports and fixes. 18426497Sache 18526497SacheChet Ramey 186165670Sachechet.ramey@case.edu 187