README revision 119610
126497SacheIntroduction 226497Sache============ 321308Sache 4119610SacheThis is the Gnu Readline library, version 4.3. 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 10547558SacheSHLIB_LIBSUFF The suffix to add to `libreadline' and `libhistory' when 10647558Sache generating the filename of the shared library. Many systems 10747558Sache use `so'; HP-UX uses `sl'. 10847558Sache 10947558SacheSHLIB_LIBVERSION The string to append to the filename to indicate the version 11047558Sache of the shared library. It should begin with $(SHLIB_LIBSUFF), 11147558Sache and possibly include version information that allows the 11247558Sache run-time loader to load the version of the shared library 11347558Sache appropriate for a particular program. Systems using shared 11447558Sache libraries similar to SunOS 4.x use major and minor library 11547558Sache version numbers; for those systems a value of 11647558Sache `$(SHLIB_LIBSUFF).$(SHLIB_MAJOR)$(SHLIB_MINOR)' is appropriate. 11747558Sache Systems based on System V Release 4 don't use minor version 11847558Sache numbers; use `$(SHLIB_LIBSUFF).$(SHLIB_MAJOR)' on those systems. 11947558Sache Other Unix versions use different schemes. 12047558Sache 12147558SacheSHLIB_STATUS Set this to `supported' when you have defined the other 12247558Sache necessary variables. Make uses this to determine whether 12347558Sache or not shared library creation should be attempted. 12447558Sache 12547558SacheYou should look at the existing stanzas in support/shobj-conf for ideas. 12647558Sache 12747558SacheOnce you have updated support/shobj-conf, re-run configure and type 12847558Sache`make shared'. The shared libraries will be created in the shlib 12947558Sachesubdirectory. 13047558Sache 131119610SacheIf shared libraries are created, `make install' will install them. 132119610SacheYou may install only the shared libraries by running `make 133119610Sacheinstall-shared' from the top-level build directory. Running `make 134119610Sacheinstall' in the shlib subdirectory will also work. If you don't want 135119610Sacheto install any created shared libraries, run `make install-static'. 13647558Sache 13726497SacheDocumentation 13826497Sache============= 13926497Sache 140119610SacheThe documentation for the Readline and History libraries appears in 141119610Sachethe `doc' subdirectory. There are three texinfo files and a 142119610SacheUnix-style manual page describing the facilities available in the 143119610SacheReadline library. The texinfo files include both user and 144119610Sacheprogrammer's manuals. HTML versions of the manuals appear in the 145119610Sache`doc' subdirectory as well. 14626497Sache 14726497SacheReporting Bugs 14826497Sache============== 14926497Sache 15026497SacheBug reports for Readline should be sent to: 15126497Sache 15235486Sache bug-readline@gnu.org 15326497Sache 15426497SacheWhen reporting a bug, please include the following information: 15526497Sache 15675406Sache * the version number and release status of Readline (e.g., 4.2-release) 15726497Sache * the machine and OS that it is running on 15826497Sache * a list of the compilation flags or the contents of `config.h', if 15926497Sache appropriate 16026497Sache * a description of the bug 16126497Sache * a recipe for recreating the bug reliably 16226497Sache * a fix for the bug if you have one! 16326497Sache 16426497SacheIf you would like to contact the Readline maintainer directly, send mail 16535486Sacheto bash-maintainers@gnu.org. 16626497Sache 16735486SacheSince Readline is developed along with bash, the bug-bash@gnu.org mailing 16835486Sachelist (mirrored to the Usenet newsgroup gnu.bash.bug) often contains 16935486SacheReadline bug reports and fixes. 17026497Sache 17126497SacheChet Ramey 17226497Sachechet@po.cwru.edu 173