root/foundation-apps/mxterm-maxx/INSTALL

-- $XTermId: INSTALL,v 1.117 2007/12/12 01:30:43 tom Exp $
-------------------------------------------------------------------------------
-- Copyright 1997-2006,2007 by Thomas E. Dickey
--
--                         All Rights Reserved
--
-- Permission is hereby granted, free of charge, to any person obtaining a
-- copy of this software and associated documentation files (the
-- "Software"), to deal in the Software without restriction, including
-- without limitation the rights to use, copy, modify, merge, publish,
-- distribute, sublicense, and/or sell copies of the Software, and to
-- permit persons to whom the Software is furnished to do so, subject to
-- the following conditions:
--
-- The above copyright notice and this permission notice shall be included
-- in all copies or substantial portions of the Software.
--
-- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
-- OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-- MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-- IN NO EVENT SHALL THE ABOVE LISTED COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
-- CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
-- TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
-- SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
--
-- Except as contained in this notice, the name(s) of the above copyright
-- holders shall not be used in advertising or otherwise to promote the
-- sale, use or other dealings in this Software without prior written
-- authorization.
-------------------------------------------------------------------------------

Xterm is normally built as part of the X Window System source tree, using
imake to generate a Makefile from Imakefile.  You can also use the
configure script to generate a Makefile from Makefile.in:

        + If you have imake (or xmkmf), then you can use those directly,
          or use the configure script, which normally uses those tools
          to obtain the special definitions needed to build xterm.

          Ultimately, imake will not be necessary, since it is possible
          to add configure tests that derive the information that imake
          would supply.

        + You need the Athena widgets (or a clone, such as Xaw3d or
          neXtaw), to provide the popup menus.

Even if you have imake, the configure script is still convenient because
it allows you to build different configurations more easily than with
imake, simply by specifying options to the configure script.

Options:
-------

Autoconf configure scripts recognize two types of application-defined
options, enable/disable and with/without.  The latter, by convention, are
used for denoting inclusion of external packages, while the former denote
enabling/disabling of internal features.  The configure --help option lists
the available options.  This script uses "enable" and "disable" to indicate
the sense of the default behavior.

The options (in alphabetic order):

  --disable-16-color      disable 16-color support

        Do not compile-in code to recognize aixterm-style control sequences
        that support color values 8-15.

        Most color applications know only about 8 ANSI colors, but some
        (e.g., ones built with ncurses) do.

  --disable-active-icon   disable X11R6.3 active-icon feature

        Do not compile-in code to support the active-icon feature.  This is
        not configured on systems (e.g., X11R5) which lack the library
        support needed.

        Xterms with an active icon continue to respond to input and update
        their display when iconified.  Not all window managers support
        active icons.  Those that do include fvwm, olvwm and mwm.

  --disable-ansi-color    disable ANSI color

        Do not compile-in code for ANSI colors.

  --disable-blink-cursor  disable support for blinking cursor

        Do not compile-in code that implements a blinking cursor.  The blinking
        cursor is enabled either by resource setting or by popup menu entry.

  --disable-bold-color    disable PC-style mapping of bold colors

        Do not compile-in code that maps colors 8-15 to bold versions of
        colors 0-7.

        Some applications have hardcoded logic that assumes this.  It does
        not interfere with the 16-color support.

  --disable-boxchars      disable fallback-support for box chars

        Do not compile-in code to generate approximations for box/graphic
        characters.

        Most fonts do not contain the vt100-style graphic characters in
        positions 0-31.  Many applications use the line-drawing characters,
        e.g., to make boxes.  When xterm loads a font, it checks if those
        characters are present, and draws its own if they are missing.

  --disable-c1-print      disallow -k8 option for printable 128-159],

        Use this option to suppress support for nonstandard use of codes
        128-159, which normally are considered control characters.  Some users
        have fonts which use those positions.  The default value for the
        allowC1Printable resource is false, so this feature does not impact
        normal users.

  --disable-color-class   disable color class resources

        Use this option to change most of the color resources to use Foreground
        as the color class.  This is the older (before patch #157) behavior
        which has the drawback that setting the Foreground resource on most
        platforms prevents use of color since the class is evaluated before
        the instance.

  --disable-color-mode    disable default colorMode resource

        Do not compile-in code that sets the default value of the colorMode
        resource to ``true''.

  --disable-desktop       disable install of xterm desktop files

        Do not install the xterm desktop files, used in menus.
        These use the icons installed in the --with-icondir option.
        Use the environment variable $DESKTOP_FLAGS to supply options
        required by desktop-file-install.

        Note: If desktop-utils is not found they will not be installed anyway.

  --disable-doublechars   disable support for double-size chars

        Do not compile-in code that supports font-manipulation needed to
        implement vt100-style double-sized characters.

  --disable-echo          test: display "compiling" commands

        Modify the generated Makefile so that most compiler options are
        not shown.  This makes it simpler to read a build log and see the
        actual warning messages.

  --disable-freetype      disable freetype library-support

        Do not use freetype libraries if they are found.  Normally they will
        be used automatically.

  --disable-full-tgetent  disable check for termcap library

        Do not look for the tgetent() function specifically in the termcap
        library, accept the first library (from termlib, ncurses and curses)
        which contains this function rather than continuing to search for
        a termcap implementation rather than terminfo.  The former would
        supply the complete $TERMCAP data needed for some legacy programs.

  --disable-highlighting  disable support for color highlighting

        Do not compile-in code that allows the selected region to be a
        different color than the reverse of foreground/background colors.

        See the discussion of highlightColor in the manual.

  --disable-i18n          disable internationalization

        Do not compile-in code to handle multi-byte characters.  This is
        related to, but not identical with the input method logic.

  --disable-imake         disable use of imake for definitions

        Do not attempt to use imake to determine compiler options.

        The main.c file has many ifdef's which rely on obscure combinations
        known only to imake.  The configure script implements only a
        portion of the tests needed to supplant imake.

  --disable-initial-erase disable setup for stty erase

        Do not compile-in code which aligns the stty erase and the backarrow
        key.  When compiled-in, xterm will optionally use the pty's sense
        of stty erase and apply that to the backarrow mode (sending 8 or 127),
        or go the other way, setting stty erase to match xterm's configuration.

  --disable-input-method  disable input-method

        Do not compile-in code for "input method".  This is an X11R6
        feature which deals with translation of composite characters.

        Some users report problems with their configuration, e.g., messages
        stating that there is no input method defined for the given preedit
        type.  If you do not need input method (and are troubled by the
        warning messages), it is safe to disable this option.

  --disable-leaks         test: set to test memory leaks

        Compile-in code which frees memory which might confuse a leak-testing
        tool.  Normally these chunks of memory are retained as long as xterm
        is running.

  --disable-maximize      disable actions for iconify/deiconify/maximize/restore

        Do not compile-in code that implements runtime 'actions' for
        iconifying, maximizing, etc.

        Most users will find that the window manager is more suitable for
        this sort of manipulation than putting the capabilities into xterm.

  --disable-num-lock      disable NumLock keypad support

        Do not compile-in code that looks for the actual NumLock key to
        support vt100/vt220 keypad translation.

        This is used in xterm to simplify logic, and to workaround some
        quirks of the keyboard tables.  Use the ``numLock'' resource to
        disable this feature if you must customize xterm in some other way.

        (The same ifdef controls the metaSendsEscape support).

  --disable-pty-handshake disable support for pty handshakes

        This feature is used to ensure that the child process's terminal modes
        match the parent's.  In particular, it addresses a problem where the
        terminal size is not defined in the stty settings.

  --disable-rectangles    disable VT420 rectangle support

        Do not compile-in code to support VT420 rectangle control-sequences.

  --disable-regex         disable regular-expression selections

        Do not compile-in code to support the "regex" option for multiple
        mouse clicks.

  --disable-rightbar      disable right-scrollbar support

        Do not compile-in code that supports a scrollbar on the right.

        Left/right scrollbars are a matter of taste.  Some older libraries
        (e.g., X11R5) do not perform the geometry computation correctly,
        leaving the right scrollbar incorrectly positioned after changing
        the font size.

  --disable-samename      disable check for redundant name-change

        Do not compile-in code that suppresses redundant updates to the
        titlebar when the text has not changed.

  --disable-session-mgt   enable support for session management

        Do not compile-in code which adds simple session management hooks
        which are used when closing an xterm.  Normally the code is
        compiled-in, except for systems which do not support it.

  --disable-setgid        disable setgid

        Do not install xterm using setuid/setgid permissions.  Drop setgid
        permissions on startup.

  --disable-setuid        disable setuid

        Do not install xterm using setuid/setgid permissions.  Drop setuid
        permissions on startup.

  --disable-sun-fkeys

        Do not compile-in code to support Sun-style function keys.

  --disable-tcap-fkeys    disable termcap function-keys

        Compile-in code to support feature which allows xterm to use the
        function-key definitions from the termcap/terminfo entry which it used
        to set the $TERM variable on startup.

  --disable-tek4014       disable tek4014 emulation

        Do not compile-in code to support Tektronix 4014 emulation.

        This reduces the executable size by 17% (checked 1999/3/13).

        Some people use the Tektronix emulation (which has been in xterm
        for many years) as an example of code bloat, though this is not an
        accurate impression.

  --disable-vt52          disable VT52 emulation

        Do not compile-in code to support vt52 emulation.

        A genuine vt100 emulates a vt52.

  --disable-ziconbeep     disable -ziconbeep option

        Do not compile-in code that modifies the icon's title and sounds a
        beep when they receive output.

  --enable-256-color      enable 256-color support

        Compile-in code that interprets SGR 38 and 48 for 256-colors.

  --enable-88-color       enable 88-color support

        Compile-in code that interprets SGR 38 and 48 for 88-colors.

  --enable-broken-osc     allow broken Linux OSC-strings],

        Compile-in code to accommodate scripts that write Linux's malformed
        palette control strings without checking.  The result makes xterm
        appear to freeze.  This workaround makes xterm ignore the strings,
        and is compiled-in by default for Linux.

  --enable-broken-st      allow broken string-terminators],

        Compile-in code that works around a bug in some ISDN routers (and
        possibly other applications written by the same people):  they send an
        unterminated control string in their banner text, making xterm freeze.
        The workaround tells xterm to stop processing the control string when
        it receives one of the whitespace control characters such as newline.
        That was the behavior before patch #171.

  --enable-dabbrev        enable dynamic-abbreviation support

        Compile-in support for "dabbrev-expand()" action and related key
        translation.

  --enable-dec-locator    enable DECterm Locator support
        Add support for DEC Locator control sequences for xterm:

                DECEFR - Enable Filter Rectangle
                DECELR - Enable Locator Reports
                DECSLE - Select Locator Events
                DECRQLP - Request Locator Position

        This allows the xterm mouse to be used with applications that use the
        DEC Locator sequences, such as VAX Tpu, or SMG$ based applications.

  --enable-exec-xterm     enable "spawn-new-terminal" action

        If your platform supports the process filesystem "cwd" link,
        compile-in support for the "spawn-new-terminal" action, which
        allows you to define a key translation that runs a new xterm
        using the same working directory as the current process within
        xterm.

  --enable-hp-fkeys       enable support for HP-style function keys

        Compile-in code to support HP-style function keys.

  --enable-load-vt-fonts  enable load-vt-fonts() action

        Compile-in code that allows user to define load different VT-font
        definitions at runtime.

  --enable-logfile-exec   enable exec'd logfile filter

        Compile-in code that allows logging piped via an external filter.

  --enable-logging        enable logging

        Compile-in code that allows logging.

        Logging was disabled in X11R5 xterm because of security problems.
        They were addressed in X11R6, but the feature was not reinstated.

  --enable-luit           enable support for luit filter (Unicode translation)

        Luit is a filter that can be run between an arbitrary application and a
        UTF-8 terminal emulator.  It will convert application output from the
        locale's encoding into UTF-8, and convert terminal input from UTF-8
        into the locale's encoding.

        This sets "--enable-wide-chars" as a side-effect.

  --enable-mini-luit      enable support for poor man's luit filter (Latin-9)

        Provide built-in support for Latin-9, relying on having specified
        Unicode (ISO10646) fonts and setting the locale resource to "checkfont".

        This sets "--enable-luit" as a side-effect.

  --enable-narrowproto    enable narrow prototypes for X libraries

        Originally xterm was built using imake rather than a configure script. 
        One feature of imake that is not possible to guess within the
        configure script is the wide-prototype compile-time definition
        NARROWPROTO.  When this is not set properly, the Athena widget
        scrollbars do not work properly.  xterm's configure script has a
        fallback case which allows disabling imake.  However, this is moot
        with the X.org "modular" build, whose compiler options are unrelated to
        imake or older versions of any libraries that it may distribute.  In
        this case, the configure script needs some help.  Use this option to
        enable or disable NARROW proto (and disable imake with the
        --disable-imake option) to match the whims of X.org hackers.

        For instance

                configure --disable-imake --disable-narrowproto

  --enable-paste64        enable support for bracketed paste mode

        Compile-in code to support experimental bracketed paste mode, i.e.,
        provide functions for setting/getting the selection data.

        (see ctlseqs.ms description of OSC 52).

  --enable-readline-mouse enable support for mouse in readline applications

        Compile-in code to support experimental bracketed paste mode, i.e.,
        provide functions for setting/getting the selection data.  Essentially
        this puts xterm into a mode that sends special function-key strings to
        bracket the data.

        (See --enable-paste64, which fits xterm's protocol better).

  --enable-sco-fkeys      enable support for SCO-style function keys

        Compile-in code to support SCO-style function keys.

  --enable-sun-fkeys      enable support for Sun-style function keys

        Compile-in code to support Sun-style function keys.

  --enable-tcap-query     enable termcap query/report

        Compile-in code to support experimental DCS '+' control sequence, which
        allows an application to ask xterm what control sequences it would
        transmit for specified function keys, given the termcap or terminfo
        names.

  --enable-toolbar        enable pulldown menus on toolbar

        Compile-in code that builds a toolbar with pulldown menus.  The
        normal popup menus are still available.

        This is an experimental option.  As of patch #206, it is known to
        work well with fvwm, but not as well with some other window managers,
        e.g., KDE's Kwin and IceWM.

        In addition to isolated layout problems, it is reported that some
        flavors of the Athena widget library perform badly with ISO-10646
        fonts.  You can work around those by setting the menu fonts to
        an ISO-8859 variant in your X resources.

  --enable-trace          test: set to enable debugging traces

        Compile-in code to trace xterm's internal states.

        This is a debugging feature.  It causes xterm to produce two files
        (Trace-parent.out and Trace-child.out).

  --enable-warnings       test: turn on GCC compiler warnings

        Modify the generate Makefile to turn on gcc compiler warnings.

        I use this option regularly, and correct all but a few (difficult)
        problems.

  --enable-wide-chars     enable wide-character support

        Compile-in code that supports 16-bit characters.  Includes support
        for UTF-8.

  --enable-xmc-glitch     test: enable xmc magic-cookie emulation

        Compile-in code that simulates the terminfo "magic cookie" glitch.

        This is for testing ncurses.

  --with-Xaw3d            link with Xaw 3d library

        Look for, compile and link with the Xaw 3d widget library.

  --with-XawPlus          link with Athena-Plus library

        Look for, compile and link with the Xaw Plus widget library.

  --with-app-defaults=DIR directory in which to install resource files (default: EPREFIX/lib/X11/app-defaults)

        autoconf scripts assume that all of the files should be installed
        under the same top-level directory.  But X applications defaults
        must be installed into a special directory, e.g.,

                /usr/X11/lib/app-defaults

        However, there is no standard for this pathname.  The manual page
        for X notes that the environment variable $XUSERFILESEARCHPATH can
        specify a list of places where X searches for applications defaults.
        Also, it may look in $XAPPLRESDIR, but that usually is not related
        to where xterm might be installed.  To keep it simple, the configure
        script uses

                EPREFIX/lib/X11/app-defaults

        as the default (EPREFIX is --prefix).  That makes it work normally
        for most systems if --prefix is /usr.  For other installs, e.g., to
        /usr/local, you should use this option to customize the location to
        match your system configuration.

        Use --without-app-defaults or --with-app-defaults=no to disable the
        feature.

  --with-freetype-cflags  -D/-I options for compiling with FreeType library

        Override options provided by xft-config or freetype-config.

  --with-freetype-libs    -L/-l options for linking with FreeType library

        Override options provided by xft-config or freetype-config.

  --with-icondir=DIR directory in which to install icon files (default: EPREFIX/share/pixmaps)

        The X libraries may automatically search these locations:

        $HOME/.icons
        $XDG_DATA_DIRS/icons
        /usr/share/pixmaps

        See also
        http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html

        Use --without-icondir or --with-icondir=no to disable the feature.

  --with-neXtaw           link with neXT Athena library

        Look for, compile and link with the neXT Athena widget library.

  --with-own-terminfo=P   set default $TERMINFO (default: from environment)

        Modify the generated Makefile to set the target for the 'install-ti'
        rule to point to the given directory.

        If you have the $TERMINFO variable defined in your environment, the
        configure script will use that value.  If no option and no variable
        are are given, the configure script uses /usr/lib/terminfo, if it
        exists.

        You do not have to run "make install-ti", if there is already a
        workable terminfo description.  Be advised, however, that the
        common variety of "xterm-color" is not suited for xterm, but is
        directed to other variations (such as nxterm) which do not
        support the background-color erase capability.

  --with-pcre             use PCRE for regular-expressions

        If regular expressions are not disable (--disable-regex), use PCRE
        rather than the POSIX regular expressions.

  --with-reference=XXX    program to use as permissions-reference

        To install xterm with setuid permissions, the scripts usually compare
        it with a previous install.  That works well for individual
        maintainers, but can be a problem for packagers who may be
        cross-compiling, etc.  This option lets the package builder specify
        the file used for permissions reference.

  --with-setuid=XXX       use the given setuid user

        Install xterm setuid'd to the given user.  If no parameter value
        is given, assume it is root.

        See also --with-utmp-setgid and --with-utempter, which manipulate
        the setgid group.

  --with-tty-group=XXX    use XXX for the tty-group

        If xterm is installed setuid'd to root, change the group of the tty
        device to the given value on startup.  Three cases are possible:
        
        a) If this option is not given, the configure script will attempt to
           find a suitable value (usually "tty"), and verify that it exists in
           the group database.

        b) If the option value is given, it will use the value even if it does
           not exist in the group database (allowing packagers to work about
           deficient environments).

        c) If the option is disabled, e.g., --without-tty-group, the
           permissions change will use the group-id of the process.

        If xterm is not installed setuid'd to root, this option is not needed,
        since it cannot change the tty device's ownership.

  --with-xterm-symlink=XXX  make symbolic link to installed xterm

        If any of the configure options to modify the program name i.e.,
        --program-prefix, --program-suffix or --program-transform-name
        are given, this option allows the makefile to create a symbolic link,
        e.g., to "xterm" on install.  The option value gives the name for
        the link, which defaults to "xterm".

        Use --without-xterm-symlink to disable a link to "xterm" if none
        is wanted.

  --with-terminal-id[=V]  set default decTerminalID (default: vt100)

        Set the default emulation level.

        DEC terminals vt52/vt100/vt220/etc form a series where succeeding
        models emulate features of the older terminals.  While most
        features of these terminals are recognized by xterm at all levels,
        a few behave differently according to the emulation level.

        You can always override this with the command-line option "-ti".

  --with-terminal-type=T  set default $TERM (default: xterm)

        Set the default value for $TERM.  Xterm supports legacy termcap
        applications by constructing a modified version of the $TERMCAP
        variable at initialization, which supplies the resulting screen
        size.  It also sets $TERM, if not already set, for use by programs
        running within xterm.

        The default value "xterm", can be overridden to avoid conflict
        with older versions of xterm, e.g., those that do not implement
        vt220 emulation.

        You can always override this with the command-line option "-tn".

  --with-utempter         use utempter library for access to utmp

        The utempter library is a set-uid wrapper for the utmp facility.
        On systems with Unix98 pty's, xterm can use this library when
        available so it need not be installed set-uid.

  --with-utmp-setgid=XXX  use setgid for access to utmp

        The option value specifies a group to use when installing.
        xterm will be installed with setgid privilege to this group.
        At runtime, xterm will drop the setuid privilege immediately
        after opening the pseudo-terminal, and will have only the
        group privilege needed to access the utmp file.  This relies
        on having POSIX setuid behavior.

-- vile:txtmode