Annotation of embedaddon/readline/README, revision 1.1

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

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>