|
jpayne@68
|
1 Introduction
|
|
jpayne@68
|
2 ============
|
|
jpayne@68
|
3
|
|
jpayne@68
|
4 This is the Gnu Readline library, version 8.2.
|
|
jpayne@68
|
5
|
|
jpayne@68
|
6 The Readline library provides a set of functions for use by applications
|
|
jpayne@68
|
7 that allow users to edit command lines as they are typed in. Both
|
|
jpayne@68
|
8 Emacs and vi editing modes are available. The Readline library includes
|
|
jpayne@68
|
9 additional functions to maintain a list of previously-entered command
|
|
jpayne@68
|
10 lines, to recall and perhaps reedit those lines, and perform csh-like
|
|
jpayne@68
|
11 history expansion on previous commands.
|
|
jpayne@68
|
12
|
|
jpayne@68
|
13 The history facilities are also placed into a separate library, the
|
|
jpayne@68
|
14 History library, as part of the build process. The History library
|
|
jpayne@68
|
15 may be used without Readline in applications which desire its
|
|
jpayne@68
|
16 capabilities.
|
|
jpayne@68
|
17
|
|
jpayne@68
|
18 The Readline library is free software, distributed under the terms of
|
|
jpayne@68
|
19 the [GNU] General Public License as published by the Free Software
|
|
jpayne@68
|
20 Foundation, version 3 of the License. For more information, see the
|
|
jpayne@68
|
21 file COPYING.
|
|
jpayne@68
|
22
|
|
jpayne@68
|
23 To build the library, try typing `./configure', then `make'. The
|
|
jpayne@68
|
24 configuration process is automated, so no further intervention should
|
|
jpayne@68
|
25 be necessary. Readline builds with `gcc' by default if it is
|
|
jpayne@68
|
26 available. If you want to use `cc' instead, type
|
|
jpayne@68
|
27
|
|
jpayne@68
|
28 CC=cc ./configure
|
|
jpayne@68
|
29
|
|
jpayne@68
|
30 if you are using a Bourne-style shell. If you are not, the following
|
|
jpayne@68
|
31 may work:
|
|
jpayne@68
|
32
|
|
jpayne@68
|
33 env CC=cc ./configure
|
|
jpayne@68
|
34
|
|
jpayne@68
|
35 Read the file INSTALL in this directory for more information about how
|
|
jpayne@68
|
36 to customize and control the build process.
|
|
jpayne@68
|
37
|
|
jpayne@68
|
38 The file rlconf.h contains C preprocessor defines that enable and disable
|
|
jpayne@68
|
39 certain Readline features.
|
|
jpayne@68
|
40
|
|
jpayne@68
|
41 The special make target `everything' will build the static and shared
|
|
jpayne@68
|
42 libraries (if the target platform supports them) and the examples.
|
|
jpayne@68
|
43
|
|
jpayne@68
|
44 Examples
|
|
jpayne@68
|
45 ========
|
|
jpayne@68
|
46
|
|
jpayne@68
|
47 There are several example programs that use Readline features in the
|
|
jpayne@68
|
48 examples directory. The `rl' program is of particular interest. It
|
|
jpayne@68
|
49 is a command-line interface to Readline, suitable for use in shell
|
|
jpayne@68
|
50 scripts in place of `read'.
|
|
jpayne@68
|
51
|
|
jpayne@68
|
52 Shared Libraries
|
|
jpayne@68
|
53 ================
|
|
jpayne@68
|
54
|
|
jpayne@68
|
55 There is skeletal support for building shared versions of the
|
|
jpayne@68
|
56 Readline and History libraries. The configure script creates
|
|
jpayne@68
|
57 a Makefile in the `shlib' subdirectory, and typing `make shared'
|
|
jpayne@68
|
58 will cause shared versions of the Readline and History libraries
|
|
jpayne@68
|
59 to be built on supported platforms.
|
|
jpayne@68
|
60
|
|
jpayne@68
|
61 If `configure' is given the `--enable-shared' option, it will attempt
|
|
jpayne@68
|
62 to build the shared libraries by default on supported platforms.
|
|
jpayne@68
|
63
|
|
jpayne@68
|
64 Configure calls the script support/shobj-conf to test whether or
|
|
jpayne@68
|
65 not shared library creation is supported and to generate the values
|
|
jpayne@68
|
66 of variables that are substituted into shlib/Makefile. If you
|
|
jpayne@68
|
67 try to build shared libraries on an unsupported platform, `make'
|
|
jpayne@68
|
68 will display a message asking you to update support/shobj-conf for
|
|
jpayne@68
|
69 your platform.
|
|
jpayne@68
|
70
|
|
jpayne@68
|
71 If you need to update support/shobj-conf, you will need to create
|
|
jpayne@68
|
72 a `stanza' for your operating system and compiler. The script uses
|
|
jpayne@68
|
73 the value of host_os and ${CC} as determined by configure. For
|
|
jpayne@68
|
74 instance, FreeBSD 4.2 with any version of gcc is identified as
|
|
jpayne@68
|
75 `freebsd4.2-gcc*'.
|
|
jpayne@68
|
76
|
|
jpayne@68
|
77 In the stanza for your operating system-compiler pair, you will need to
|
|
jpayne@68
|
78 define several variables. They are:
|
|
jpayne@68
|
79
|
|
jpayne@68
|
80 SHOBJ_CC The C compiler used to compile source files into shareable
|
|
jpayne@68
|
81 object files. This is normally set to the value of ${CC}
|
|
jpayne@68
|
82 by configure, and should not need to be changed.
|
|
jpayne@68
|
83
|
|
jpayne@68
|
84 SHOBJ_CFLAGS Flags to pass to the C compiler ($SHOBJ_CC) to create
|
|
jpayne@68
|
85 position-independent code. If you are using gcc, this
|
|
jpayne@68
|
86 should probably be set to `-fpic'.
|
|
jpayne@68
|
87
|
|
jpayne@68
|
88 SHOBJ_LD The link editor to be used to create the shared library from
|
|
jpayne@68
|
89 the object files created by $SHOBJ_CC. If you are using
|
|
jpayne@68
|
90 gcc, a value of `gcc' will probably work.
|
|
jpayne@68
|
91
|
|
jpayne@68
|
92 SHOBJ_LDFLAGS Flags to pass to SHOBJ_LD to enable shared object creation.
|
|
jpayne@68
|
93 If you are using gcc, `-shared' may be all that is necessary.
|
|
jpayne@68
|
94 These should be the flags needed for generic shared object
|
|
jpayne@68
|
95 creation.
|
|
jpayne@68
|
96
|
|
jpayne@68
|
97 SHLIB_XLDFLAGS Additional flags to pass to SHOBJ_LD for shared library
|
|
jpayne@68
|
98 creation. Many systems use the -R option to the link
|
|
jpayne@68
|
99 editor to embed a path within the library for run-time
|
|
jpayne@68
|
100 library searches. A reasonable value for such systems would
|
|
jpayne@68
|
101 be `-R$(libdir)'.
|
|
jpayne@68
|
102
|
|
jpayne@68
|
103 SHLIB_LIBS Any additional libraries that shared libraries should be
|
|
jpayne@68
|
104 linked against when they are created.
|
|
jpayne@68
|
105
|
|
jpayne@68
|
106 SHLIB_LIBPREF The prefix to use when generating the filename of the shared
|
|
jpayne@68
|
107 library. The default is `lib'; Cygwin uses `cyg'.
|
|
jpayne@68
|
108
|
|
jpayne@68
|
109 SHLIB_LIBSUFF The suffix to add to `libreadline' and `libhistory' when
|
|
jpayne@68
|
110 generating the filename of the shared library. Many systems
|
|
jpayne@68
|
111 use `so'; HP-UX uses `sl'.
|
|
jpayne@68
|
112
|
|
jpayne@68
|
113 SHLIB_LIBVERSION The string to append to the filename to indicate the version
|
|
jpayne@68
|
114 of the shared library. It should begin with $(SHLIB_LIBSUFF),
|
|
jpayne@68
|
115 and possibly include version information that allows the
|
|
jpayne@68
|
116 run-time loader to load the version of the shared library
|
|
jpayne@68
|
117 appropriate for a particular program. Systems using shared
|
|
jpayne@68
|
118 libraries similar to SunOS 4.x use major and minor library
|
|
jpayne@68
|
119 version numbers; for those systems a value of
|
|
jpayne@68
|
120 `$(SHLIB_LIBSUFF).$(SHLIB_MAJOR)$(SHLIB_MINOR)' is appropriate.
|
|
jpayne@68
|
121 Systems based on System V Release 4 don't use minor version
|
|
jpayne@68
|
122 numbers; use `$(SHLIB_LIBSUFF).$(SHLIB_MAJOR)' on those systems.
|
|
jpayne@68
|
123 Other Unix versions use different schemes.
|
|
jpayne@68
|
124
|
|
jpayne@68
|
125 SHLIB_DLLVERSION The version number for shared libraries that determines API
|
|
jpayne@68
|
126 compatibility between readline versions and the underlying
|
|
jpayne@68
|
127 system. Used only on Cygwin. Defaults to $SHLIB_MAJOR, but
|
|
jpayne@68
|
128 can be overridden at configuration time by defining DLLVERSION
|
|
jpayne@68
|
129 in the environment.
|
|
jpayne@68
|
130
|
|
jpayne@68
|
131 SHLIB_DOT The character used to separate the name of the shared library
|
|
jpayne@68
|
132 from the suffix and version information. The default is `.';
|
|
jpayne@68
|
133 systems like Cygwin which don't separate version information
|
|
jpayne@68
|
134 from the library name should set this to the empty string.
|
|
jpayne@68
|
135
|
|
jpayne@68
|
136 SHLIB_STATUS Set this to `supported' when you have defined the other
|
|
jpayne@68
|
137 necessary variables. Make uses this to determine whether
|
|
jpayne@68
|
138 or not shared library creation should be attempted.
|
|
jpayne@68
|
139
|
|
jpayne@68
|
140 You should look at the existing stanzas in support/shobj-conf for ideas.
|
|
jpayne@68
|
141
|
|
jpayne@68
|
142 Once you have updated support/shobj-conf, re-run configure and type
|
|
jpayne@68
|
143 `make shared'. The shared libraries will be created in the shlib
|
|
jpayne@68
|
144 subdirectory.
|
|
jpayne@68
|
145
|
|
jpayne@68
|
146 If shared libraries are created, `make install' will install them.
|
|
jpayne@68
|
147 You may install only the shared libraries by running `make
|
|
jpayne@68
|
148 install-shared' from the top-level build directory. Running `make
|
|
jpayne@68
|
149 install' in the shlib subdirectory will also work. If you don't want
|
|
jpayne@68
|
150 to install any created shared libraries, run `make install-static'.
|
|
jpayne@68
|
151
|
|
jpayne@68
|
152 Documentation
|
|
jpayne@68
|
153 =============
|
|
jpayne@68
|
154
|
|
jpayne@68
|
155 The documentation for the Readline and History libraries appears in
|
|
jpayne@68
|
156 the `doc' subdirectory. There are three texinfo files and a
|
|
jpayne@68
|
157 Unix-style manual page describing the facilities available in the
|
|
jpayne@68
|
158 Readline library. The texinfo files include both user and
|
|
jpayne@68
|
159 programmer's manuals. HTML versions of the manuals appear in the
|
|
jpayne@68
|
160 `doc' subdirectory as well.
|
|
jpayne@68
|
161
|
|
jpayne@68
|
162 Usage
|
|
jpayne@68
|
163 =====
|
|
jpayne@68
|
164
|
|
jpayne@68
|
165 Our position on the use of Readline through a shared-library linking
|
|
jpayne@68
|
166 mechanism is that there is no legal difference between shared-library
|
|
jpayne@68
|
167 linking and static linking--either kind of linking combines various
|
|
jpayne@68
|
168 modules into a single larger work. The conditions for using Readline
|
|
jpayne@68
|
169 in a larger work are stated in section 3 of the GNU GPL.
|
|
jpayne@68
|
170
|
|
jpayne@68
|
171 Reporting Bugs
|
|
jpayne@68
|
172 ==============
|
|
jpayne@68
|
173
|
|
jpayne@68
|
174 Bug reports for Readline should be sent to:
|
|
jpayne@68
|
175
|
|
jpayne@68
|
176 bug-readline@gnu.org
|
|
jpayne@68
|
177
|
|
jpayne@68
|
178 When reporting a bug, please include the following information:
|
|
jpayne@68
|
179
|
|
jpayne@68
|
180 * the version number and release status of Readline (e.g., 4.2-release)
|
|
jpayne@68
|
181 * the machine and OS that it is running on
|
|
jpayne@68
|
182 * a list of the compilation flags or the contents of `config.h', if
|
|
jpayne@68
|
183 appropriate
|
|
jpayne@68
|
184 * a description of the bug
|
|
jpayne@68
|
185 * a recipe for recreating the bug reliably
|
|
jpayne@68
|
186 * a fix for the bug if you have one!
|
|
jpayne@68
|
187
|
|
jpayne@68
|
188 If you would like to contact the Readline maintainer directly, send mail
|
|
jpayne@68
|
189 to bash-maintainers@gnu.org.
|
|
jpayne@68
|
190
|
|
jpayne@68
|
191 Since Readline is developed along with bash, the bug-bash@gnu.org mailing
|
|
jpayne@68
|
192 list (mirrored to the Usenet newsgroup gnu.bash.bug) often contains
|
|
jpayne@68
|
193 Readline bug reports and fixes.
|
|
jpayne@68
|
194
|
|
jpayne@68
|
195 Chet Ramey
|
|
jpayne@68
|
196 chet.ramey@case.edu
|
