annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/doc/readline/INSTALL @ 68:5028fdace37b

planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 16:23:26 -0400
parents
children
rev   line source
jpayne@68 1 Basic Installation
jpayne@68 2 ==================
jpayne@68 3
jpayne@68 4 These are installation instructions for Readline-8.2.
jpayne@68 5
jpayne@68 6 The simplest way to compile readline is:
jpayne@68 7
jpayne@68 8 1. `cd' to the directory containing the readline source code and type
jpayne@68 9 `./configure' to configure readline for your system. If you're
jpayne@68 10 using `csh' on an old version of System V, you might need to type
jpayne@68 11 `sh ./configure' instead to prevent `csh' from trying to execute
jpayne@68 12 `configure' itself.
jpayne@68 13
jpayne@68 14 Running `configure' takes some time. While running, it prints some
jpayne@68 15 messages telling which features it is checking for.
jpayne@68 16
jpayne@68 17 2. Type `make' to compile readline and build the static readline
jpayne@68 18 and history libraries. If supported, the shared readline and history
jpayne@68 19 libraries will be built also. See below for instructions on compiling
jpayne@68 20 the other parts of the distribution. Typing `make everything' will
jpayne@68 21 cause the static and shared libraries (if supported) and the example
jpayne@68 22 programs to be built.
jpayne@68 23
jpayne@68 24 3. Type `make install' to install the static readline and history
jpayne@68 25 libraries, the readline include files, the documentation, and, if
jpayne@68 26 supported, the shared readline and history libraries.
jpayne@68 27
jpayne@68 28 4. You can remove the created libraries and object files from the
jpayne@68 29 build directory by typing `make clean'. To also remove the
jpayne@68 30 files that `configure' created (so you can compile readline for
jpayne@68 31 a different kind of computer), type `make distclean'. There is
jpayne@68 32 also a `make maintainer-clean' target, but that is intended mainly
jpayne@68 33 for the readline developers, and should be used with care.
jpayne@68 34
jpayne@68 35 The `configure' shell script attempts to guess correct values for
jpayne@68 36 various system-dependent variables used during compilation. It
jpayne@68 37 uses those values to create a `Makefile' in the build directory,
jpayne@68 38 and Makefiles in the `doc', `shlib', and `examples'
jpayne@68 39 subdirectories. It also creates a `config.h' file containing
jpayne@68 40 system-dependent definitions. Finally, it creates a shell script
jpayne@68 41 `config.status' that you can run in the future to recreate the
jpayne@68 42 current configuration, a file `config.cache' that saves the
jpayne@68 43 results of its tests to speed up reconfiguring, and a file
jpayne@68 44 `config.log' containing compiler output (useful mainly for
jpayne@68 45 debugging `configure').
jpayne@68 46
jpayne@68 47 If you need to do unusual things to compile readline, please try
jpayne@68 48 to figure out how `configure' could check whether to do them, and
jpayne@68 49 mail diffs or instructions to <bug-readline@gnu.org> so they can
jpayne@68 50 be considered for the next release. If at some point
jpayne@68 51 `config.cache' contains results you don't want to keep, you may
jpayne@68 52 remove or edit it.
jpayne@68 53
jpayne@68 54 The file `configure.in' is used to create `configure' by a
jpayne@68 55 program called `autoconf'. You only need `configure.in' if you
jpayne@68 56 want to change it or regenerate `configure' using a newer version
jpayne@68 57 of `autoconf'. The readline `configure.in' requires autoconf
jpayne@68 58 version 2.69 or newer.
jpayne@68 59
jpayne@68 60 Compilers and Options
jpayne@68 61 =====================
jpayne@68 62
jpayne@68 63 Some systems require unusual options for compilation or linking that
jpayne@68 64 the `configure' script does not know about. You can give `configure'
jpayne@68 65 initial values for variables by setting them in the environment. Using
jpayne@68 66 a Bourne-compatible shell, you can do that on the command line like
jpayne@68 67 this:
jpayne@68 68
jpayne@68 69 CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure
jpayne@68 70
jpayne@68 71 Or on systems that have the `env' program, you can do it like this:
jpayne@68 72
jpayne@68 73 env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure
jpayne@68 74
jpayne@68 75 Compiling For Multiple Architectures
jpayne@68 76 ====================================
jpayne@68 77
jpayne@68 78 You can compile readline for more than one kind of computer at the
jpayne@68 79 same time, by placing the object files for each architecture in their
jpayne@68 80 own directory. To do this, you must use a version of `make' that
jpayne@68 81 supports the `VPATH' variable, such as GNU `make'. `cd' to the
jpayne@68 82 directory where you want the object files and executables to go and run
jpayne@68 83 the `configure' script. `configure' automatically checks for the
jpayne@68 84 source code in the directory that `configure' is in and in `..'.
jpayne@68 85
jpayne@68 86 If you have to use a `make' that does not supports the `VPATH'
jpayne@68 87 variable, you have to compile readline for one architecture at a
jpayne@68 88 time in the source code directory. After you have installed
jpayne@68 89 readline for one architecture, use `make distclean' before
jpayne@68 90 reconfiguring for another architecture.
jpayne@68 91
jpayne@68 92 Installation Names
jpayne@68 93 ==================
jpayne@68 94
jpayne@68 95 By default, `make install' will install the readline libraries in
jpayne@68 96 `/usr/local/lib', the include files in
jpayne@68 97 `/usr/local/include/readline', the man pages in `/usr/local/man',
jpayne@68 98 and the info files in `/usr/local/info'. You can specify an
jpayne@68 99 installation prefix other than `/usr/local' by giving `configure'
jpayne@68 100 the option `--prefix=PATH' or by supplying a value for the
jpayne@68 101 DESTDIR variable when running `make install'.
jpayne@68 102
jpayne@68 103 You can specify separate installation prefixes for
jpayne@68 104 architecture-specific files and architecture-independent files.
jpayne@68 105 If you give `configure' the option `--exec-prefix=PATH', the
jpayne@68 106 readline Makefiles will use PATH as the prefix for installing the
jpayne@68 107 libraries. Documentation and other data files will still use the
jpayne@68 108 regular prefix.
jpayne@68 109
jpayne@68 110 Specifying the System Type
jpayne@68 111 ==========================
jpayne@68 112
jpayne@68 113 There may be some features `configure' can not figure out
jpayne@68 114 automatically, but need to determine by the type of host readline
jpayne@68 115 will run on. Usually `configure' can figure that out, but if it
jpayne@68 116 prints a message saying it can not guess the host type, give it
jpayne@68 117 the `--host=TYPE' option. TYPE can either be a short name for
jpayne@68 118 the system type, such as `sun4', or a canonical name with three
jpayne@68 119 fields: CPU-COMPANY-SYSTEM (e.g., i386-unknown-freebsd4.2).
jpayne@68 120
jpayne@68 121 See the file `config.sub' for the possible values of each field.
jpayne@68 122
jpayne@68 123 Sharing Defaults
jpayne@68 124 ================
jpayne@68 125
jpayne@68 126 If you want to set default values for `configure' scripts to share,
jpayne@68 127 you can create a site shell script called `config.site' that gives
jpayne@68 128 default values for variables like `CC', `cache_file', and `prefix'.
jpayne@68 129 `configure' looks for `PREFIX/share/config.site' if it exists, then
jpayne@68 130 `PREFIX/etc/config.site' if it exists. Or, you can set the
jpayne@68 131 `CONFIG_SITE' environment variable to the location of the site script.
jpayne@68 132 A warning: the readline `configure' looks for a site script, but not
jpayne@68 133 all `configure' scripts do.
jpayne@68 134
jpayne@68 135 Operation Controls
jpayne@68 136 ==================
jpayne@68 137
jpayne@68 138 `configure' recognizes the following options to control how it
jpayne@68 139 operates.
jpayne@68 140
jpayne@68 141 `--cache-file=FILE'
jpayne@68 142 Use and save the results of the tests in FILE instead of
jpayne@68 143 `./config.cache'. Set FILE to `/dev/null' to disable caching, for
jpayne@68 144 debugging `configure'.
jpayne@68 145
jpayne@68 146 `--help'
jpayne@68 147 Print a summary of the options to `configure', and exit.
jpayne@68 148
jpayne@68 149 `--quiet'
jpayne@68 150 `--silent'
jpayne@68 151 `-q'
jpayne@68 152 Do not print messages saying which checks are being made.
jpayne@68 153
jpayne@68 154 `--srcdir=DIR'
jpayne@68 155 Look for the package's source code in directory DIR. Usually
jpayne@68 156 `configure' can determine that directory automatically.
jpayne@68 157
jpayne@68 158 `--version'
jpayne@68 159 Print the version of Autoconf used to generate the `configure'
jpayne@68 160 script, and exit.
jpayne@68 161
jpayne@68 162 `configure' also accepts some other, not widely useful, options.
jpayne@68 163
jpayne@68 164 Optional Features
jpayne@68 165 =================
jpayne@68 166
jpayne@68 167 The readline `configure' recognizes two `--with-PACKAGE' options:
jpayne@68 168
jpayne@68 169 `--with-curses'
jpayne@68 170 This tells readline that it can find the termcap library functions
jpayne@68 171 (tgetent, et al.) in the curses library, rather than a separate
jpayne@68 172 termcap library. Readline uses the termcap functions, but does not
jpayne@68 173 usually link with the termcap or curses library itself, allowing
jpayne@68 174 applications which link with readline the to choose an appropriate
jpayne@68 175 library. This option tells readline to link the example programs with
jpayne@68 176 the curses library rather than libtermcap.
jpayne@68 177
jpayne@68 178 `--with-shared-termcap-library'
jpayne@68 179 This tells the readline build process to link the shared version of
jpayne@68 180 libreadline against a shared version of the curses or termcap library
jpayne@68 181 (see the description of SHLIB_LIBS below under `Shared Libraries').
jpayne@68 182 This relieves the application of having to link with curses or termcap
jpayne@68 183 itself, but does not allow the application to choose which library to
jpayne@68 184 use. This is only effective on systems that build shared libraries (see
jpayne@68 185 below; the default for shared libraries is `yes').
jpayne@68 186
jpayne@68 187 `configure' also recognizes several `--enable-FEATURE' options:
jpayne@68 188
jpayne@68 189 `--enable-bracketed-paste-default'
jpayne@68 190 Enable bracketed paste by default, so the initial value of the
jpayne@68 191 `enable-bracketed-paste' Readline variable is `on'. The default
jpayne@68 192 is `yes'.
jpayne@68 193
jpayne@68 194 `--enable-install-examples'
jpayne@68 195 Install the readline example programs as part of `make install'.
jpayne@68 196
jpayne@68 197 `--enable-multibyte'
jpayne@68 198 Build with support for multibyte characters enabled on systems with the
jpayne@68 199 necessary framework (locale definitions, C library functions, etc.). The
jpayne@68 200 default is `yes'.
jpayne@68 201
jpayne@68 202 `--enable-shared'
jpayne@68 203 Build the shared libraries by default on supported platforms. The
jpayne@68 204 default is `yes'.
jpayne@68 205
jpayne@68 206 `--enable-static'
jpayne@68 207 Build the static libraries by default. The default is `yes'.
jpayne@68 208
jpayne@68 209 Shared Libraries
jpayne@68 210 ================
jpayne@68 211
jpayne@68 212 There is support for building shared versions of the readline and
jpayne@68 213 history libraries. The configure script creates a Makefile in
jpayne@68 214 the `shlib' subdirectory, and typing `make shared' will cause
jpayne@68 215 shared versions of the readline and history libraries to be built
jpayne@68 216 on supported platforms.
jpayne@68 217
jpayne@68 218 If `configure' is given the `--enable-shared' option, it will attempt
jpayne@68 219 to build the shared libraries by default on supported platforms. This
jpayne@68 220 option is enabled by default.
jpayne@68 221
jpayne@68 222 Configure calls the script support/shobj-conf to test whether or
jpayne@68 223 not shared library creation is supported and to generate the values
jpayne@68 224 of variables that are substituted into shlib/Makefile. If you
jpayne@68 225 try to build shared libraries on an unsupported platform, `make'
jpayne@68 226 will display a message asking you to update support/shobj-conf for
jpayne@68 227 your platform.
jpayne@68 228
jpayne@68 229 If you need to update support/shobj-conf, you will need to create
jpayne@68 230 a `stanza' for your operating system and compiler. The script uses
jpayne@68 231 the value of host_os and ${CC} as determined by configure. For
jpayne@68 232 instance, FreeBSD 4.2 with any version of gcc is identified as
jpayne@68 233 `freebsd4.2-gcc*'.
jpayne@68 234
jpayne@68 235 In the stanza for your operating system-compiler pair, you will need to
jpayne@68 236 define several variables. They are:
jpayne@68 237
jpayne@68 238 SHOBJ_CC The C compiler used to compile source files into shareable
jpayne@68 239 object files. This is normally set to the value of ${CC}
jpayne@68 240 by configure, and should not need to be changed.
jpayne@68 241
jpayne@68 242 SHOBJ_CFLAGS Flags to pass to the C compiler ($SHOBJ_CC) to create
jpayne@68 243 position-independent code. If you are using gcc, this
jpayne@68 244 should probably be set to `-fpic'.
jpayne@68 245
jpayne@68 246 SHOBJ_LD The link editor to be used to create the shared library from
jpayne@68 247 the object files created by $SHOBJ_CC. If you are using
jpayne@68 248 gcc, a value of `gcc' will probably work.
jpayne@68 249
jpayne@68 250 SHOBJ_LDFLAGS Flags to pass to SHOBJ_LD to enable shared object creation.
jpayne@68 251 If you are using gcc, `-shared' may be all that is necessary.
jpayne@68 252 These should be the flags needed for generic shared object
jpayne@68 253 creation.
jpayne@68 254
jpayne@68 255 SHLIB_XLDFLAGS Additional flags to pass to SHOBJ_LD for shared library
jpayne@68 256 creation. Many systems use the -R option to the link
jpayne@68 257 editor to embed a path within the library for run-time
jpayne@68 258 library searches. A reasonable value for such systems would
jpayne@68 259 be `-R$(libdir)'.
jpayne@68 260
jpayne@68 261 SHLIB_LIBS Any additional libraries that shared libraries should be
jpayne@68 262 linked against when they are created.
jpayne@68 263
jpayne@68 264 SHLIB_LIBPREF The prefix to use when generating the filename of the shared
jpayne@68 265 library. The default is `lib'; Cygwin uses `cyg'.
jpayne@68 266
jpayne@68 267 SHLIB_LIBSUFF The suffix to add to `libreadline' and `libhistory' when
jpayne@68 268 generating the filename of the shared library. Many systems
jpayne@68 269 use `so'; HP-UX uses `sl'.
jpayne@68 270
jpayne@68 271 SHLIB_LIBVERSION The string to append to the filename to indicate the version
jpayne@68 272 of the shared library. It should begin with $(SHLIB_LIBSUFF),
jpayne@68 273 and possibly include version information that allows the
jpayne@68 274 run-time loader to load the version of the shared library
jpayne@68 275 appropriate for a particular program. Systems using shared
jpayne@68 276 libraries similar to SunOS 4.x use major and minor library
jpayne@68 277 version numbers; for those systems a value of
jpayne@68 278 `$(SHLIB_LIBSUFF).$(SHLIB_MAJOR)$(SHLIB_MINOR)' is appropriate.
jpayne@68 279 Systems based on System V Release 4 don't use minor version
jpayne@68 280 numbers; use `$(SHLIB_LIBSUFF).$(SHLIB_MAJOR)' on those systems.
jpayne@68 281 Other Unix versions use different schemes.
jpayne@68 282
jpayne@68 283 SHLIB_DLLVERSION The version number for shared libraries that determines API
jpayne@68 284 compatibility between readline versions and the underlying
jpayne@68 285 system. Used only on Cygwin. Defaults to $SHLIB_MAJOR, but
jpayne@68 286 can be overridden at configuration time by defining DLLVERSION
jpayne@68 287 in the environment.
jpayne@68 288
jpayne@68 289 SHLIB_DOT The character used to separate the name of the shared library
jpayne@68 290 from the suffix and version information. The default is `.';
jpayne@68 291 systems like Cygwin which don't separate version information
jpayne@68 292 from the library name should set this to the empty string.
jpayne@68 293
jpayne@68 294 SHLIB_STATUS Set this to `supported' when you have defined the other
jpayne@68 295 necessary variables. Make uses this to determine whether
jpayne@68 296 or not shared library creation should be attempted. If
jpayne@68 297 shared libraries are not supported, this will be set to
jpayne@68 298 `unsupported'.
jpayne@68 299
jpayne@68 300 You should look at the existing stanzas in support/shobj-conf for ideas.
jpayne@68 301
jpayne@68 302 Once you have updated support/shobj-conf, re-run configure and type
jpayne@68 303 `make shared' or `make'. The shared libraries will be created in the
jpayne@68 304 shlib subdirectory.
jpayne@68 305
jpayne@68 306 If shared libraries are created, `make install' will install them.
jpayne@68 307 You may install only the shared libraries by running `make
jpayne@68 308 install-shared' from the top-level build directory. Running `make
jpayne@68 309 install' in the shlib subdirectory will also work. If you don't want
jpayne@68 310 to install any created shared libraries, run `make install-static'.