Configuring vile and xvile                                         version 9.8
--------------------------                                         -----------

                           Configuring vile and xvile

   This file describes the steps which are needed to configure and make
   either vile or xvile. See the file README for a blurb on what (x)vile is
   and how great it is :-). The file INSTALL contains generic information on
   the process of configuring and building programs which (more or less)
   conform to the GNU coding standards. You might want to consult that
   document for more information.


Building vile
-------------
   To build vile, enter the following command from your shell:

         ./configure; make

   If you'd like to examine makefile and config.h prior to making, split
   these steps up as follows:

         ./configure
         make

   If you are unfortunate enough to be running on a platform in which some
   part of the above process does not work perfectly, you might well want to
   modify makefile to add references to obscure libraries or non-standard
   library locations.

   [ At least one version of bash running on Linux (and perhaps other)
   systems will cause the configure script to produce invalid results.
   Specifically, if you're running version 1.14.3 of bash consider upgrading
   to a newer one. ]

   Modifying makefile is not recommended because your changes will be lost
   should you run configure again. Many configuration options can be set
   externally to the configure script or the makefile. For instance, if you'd
   like to change some of the flags passed to the C compiler, try doing it
   like this:

         make CFLAGS=-O2

   Or, this can be done when running the configure script instead -- try:

         CFLAGS=-O2 ./configure                  (sh, ksh, bash)

   or:

         (setenv CFLAGS -O2 ; ./configure)       (csh)

   Then again, a configure script argument is shell-agnostic:

         ./configure --with-cflags=-O2

   If you need to suppress your optimizer (which is invoked as -O by
   default), because it's known to be buggy, use CFLAGS=" ". [ One
   combination thought to be buggy is AIX 3.2.5 with gcc 2.6.0. ]

   The configure script will favor using gcc on your system if available.
   This is usually fine, but if gcc was not installed correctly (or your
   environment isn't quite right), it can be disastrous. You can override the
   choice of compiler with:

         CC=cc ./configure               (sh, ksh, bash)

   or:

         (setenv CC cc ; ./configure)    (csh)

   Likewise, extra link libraries can be added by setting them in LIBS before
   running configure.


Screen Types
------------
   Vile is configured and built with a terminal driver. At this time, only
   one driver is built with vile at a time. Some other editors attempt to
   combine more than one driver in the default configuration, making the
   resulting program much larger and slower. We will ultimately modify vile
   to support multiple drivers, but the default configuration will be the
   smallest and fastest.

   There are several types of terminal driver:

     * text terminals
     * X Window displays
     * Win32 displays, when building in MSYS for MinGW
     * Special displays, e.g., for OS/2

   The configure script provides an option for selecting a text, X Window or
   even Win32 display. Use the "--with-screen" option to specify the driver
   type, e.g.,

         ./configure --with-screen=tcap

   Some of the choices use mixed-case, e.g., "Athena". The configure script
   also recognizes the lowercase form of each of those names, in this
   instance "athena".

  Text Terminal Drivers

   There are several choices, listed here in their order of capabilities:

   --with-screen=ncursesw
   --with-screen=tcap (default)
   --with-screen=ncurses
   --with-screen=curses
   --with-screen=ansi

   The default configuration for vile uses termcap (or terminfo, depending on
   what your system has available). That is the default because it is the
   most widely available. The "ncursesw" configuration provides better
   optimization of the terminal's capabilities, e.g., for scrolling and
   combining video attributes. Most users would not see a difference between
   the two choices.

   The configuration script tests several possibilities for each choice. Your
   system may have more than one library to link against, e.g., on Linux you
   may have both termcap and ncurses (a terminfo-based system). If you wish
   to use color, you are generally better off using terminfo, since termcap
   descriptions usually are limited to a fixed size, and some features are
   omitted. The termcap databases also tend to not be as well-maintained as
   their terminfo counterparts.

   In addition to "ncursesw", two other forms of "curses" driver are
   supported:

     * curses
     * ncurses

   They both use the same driver source, but "ncurses" tells the configure
   script to look for the ncurses library, which may not be the default
   curses implementation on your machine. Like "ncursesw", these can provide
   better optimization of the terminal than the termcap/terminfo driver.

     However, the "ncursesw" driver is more likely to support multibyte
     encodings such as UTF-8 than the other choices. The $term-encoding
     variable shows at runtime what the driver is actually doing, whether
     "locale" (capable of switching), "utf8" or "8bit".

   The "ansi" driver is the least capable. It uses built-in ANSI escape
   sequences.

   The "--with-ncurses" option is used as a special case of the default
   termcap/terminfo driver, to ensure that it uses the ncurses library rather
   than a termcap-only library.

  X Window Drivers

   There are several choices, again listed in

   --with-screen=Motif
   --with-screen=Athena
   --with-screen=Xaw
   --with-screen=Xaw3d
   --with-screen=neXtaw
   --with-screen=X11

   The Motif display has the nicest appearance. The one drawback (relative to
   Athena) is that dragging the separator between window panes is done on the
   scrollbar. The Athena interface allows you to drag the separator by
   clicking on the status-line of a window, and moving the mouse.

   "Athena" and "Xaw" are the same; the two values are given to make the
   script simpler to use. The "Xaw", "Xaw3d" and "neXtaw" choices are almost
   the same, choosing libraries that have the same capabilities but different
   appearances.

  Win32 Drivers

   If you are building vile in the MSYS environment, i.e., compiling for
   MinGW, you can build "convile" or "minvile" instead of the text- or
   X-choices:

   --with-screen=DOS
   --with-screen=Windows

   The "DOS" and "Windows" choices are comparable in functionality to the
   executables built using Visual C++.


UTF-8 Support versus Driver
---------------------------
   vile supports UTF-8 in two ways:

     * it edits UTF-8 data as characters rather than bytes and
     * it can display UTF-8 data.

   The ability to manipulate UTF-8 data depends on the operating system and
   your locale settings. The ability to display UTF-8 data depends on the
   terminal driver. If the terminal driver is unable to render UTF-8 data,
   vile displays it using "\u" sequences.

   In the choices for text-drivers, ncursesw is before tcap and ncurses after
   because of their support for UTF-8 The "ncurses" library supports 8-bit
   encodings, and cannot display UTF-8. Both "ncursesw" and the
   termcap/terminfo drivers can display UTF-8, as long as your locale
   settings support it.

   The X Window drivers all support UTF-8. Currently that is for single-width
   characters (in contrast to the text- and Win32 drivers). There is no
   support (yet) for combining characters.

   Win32 drivers support UTF-8. But they display based on font selection. The
   "Lucida Console" font is widely available, and can be used for this
   purpose. To have complete support for UTF-8, you need the fonts provided
   with Microsoft Office.


Syntax coloring options
-----------------------
   Adding syntax coloring to the editor can be simple or not.

  Fast, simple syntax coloring

   Maximally efficient syntax coloring can be selected by specifying this
   configure command line:

         --with-builtin-filters

   An ensuing build binds _all_ of the editor's syntax coloring filters into
   the resultant executable. On the plus side, the build options are simple
   and since no filters are invoked externally (via a pipe), syntax coloring
   is executed with minimal overhead. On the minus side, this configure
   option generates a much larger executable.

  Slower, simple syntax coloring

   Omitting any variant of the --with-builtin-filters option or specifying
   "--with-builtin-filters=none" ensures that all of the editor's syntax
   coloring filters are created as separate, external executables. On the
   plus side, this choice minimizes the editor's footprint. However, external
   filters are invoked via a pipe, which is substantially slower than the
   direct execution model.

  Complex syntax coloring

   vile also supports a mix of both internal and external filters, which
   facilitates configuration of the editor with as few or as many internal
   filters as desired. But before describing how this is achieved, note the
   breadth of the following table of editor filter names and language
   mappings:

   Builtin Filter External Filter Name Colors These Language(s)/Files
   Name
   ada            vile-ada-filt        ada
   as             vile-as-filt         GNU assembler (x86)
   asm            vile-asm-filt        Microsoft ASM (x86)
   au3            vile-au3-filt        au3
   awk            vile-awk-filt        awk
   basic          vile-basic-filt      basic and visual basic (vb, vbs)
   bat            vile-bat-filt        Windows .bat files
   bnf            vile-bnf-filt        BNF files
   c              vile-c-filt          c, cpp, java, and javascript (js)
   cfg            vile-cfg-filt        lynx config files
   conf           vile-conf-filt       ordinary config files
   css            vile-css-filt        cascading style-sheets
   cweb           vile-cweb-filt       cweb and cwebx
   dcl            vile-dcl-filt        VMS DCL scripts
   def            vile-def-filt        Windows .def files
   diff           vile-diff-filt       output of diff command
   ecl            vile-ecl-filt        Prolog/ECLiPSe
   erl            vile-erl-filt        Erlang
   esql           vile-esql-filt       embedded SQL with C/C++.
   est            vile-est-filt        Enscript syntax-descriptions
   fdl            vile-fdl-filt        forms definition language
   html           vile-html-filt       HTML, JSP
   imake          vile-imake-filt      imake files
   info           vile-info-filt       GNU info files
   ini            vile-ini-filt        Windows .ini, .reg, .vbp files
   iss            vile-iss-filt        InnoSetup
   key            vile-key-filt        vile .keyword files
   latex          vile-latex-filt      LaTeX
   lex            vile-lex-filt        flex and lex
   lisp           vile-lisp-filt       lisp, scheme
   lua            vile-lua-filt        Lua
   m4             vile-m4-filt         autoconf and m4
   mail           vile-mail-filt       messages
   make           vile-make-filt       make and nmake files
   mcrl           vile-mcrl-filt       mCRL/mCRL2 modeling language.
   midl           vile-midl-filt       Microsoft IDL
   mms            vile-mms-filt        VMS make files
   nr             vile-nr-filt         nroff/troff files
   pas            vile-pas-filt        Pascal, Delphi
   php            vile-php-filt        PHP
   pl             vile-pl-filt         Perl
   pot            vile-pot-filt        gettext (.po) files
   ps             vile-ps-filt         PostScript
   py             vile-py-filt         python
   rc             vile-rc-filt         Windows resource (.rc) files
   rcs            vile-rcs-filt        RCS archives
   rexx           vile-rexx-filt       REXX
   rpm            vile-rpm-filt        RPM .spec files
   rtf            vile-rtf-filt        Rich Text Format
   rb             vile-ruby-filt       Ruby
   sccs           vile-sccs-filt       SCCS files
   sed            vile-sed-filt        sed scripts
   sh             vile-sh-filt         csh, sh, PCLI
   sml            vile-sml-filt        SML input text
   spell          vile-spell-filt      highlight misspelled words using
                                       ispell or spell (see filters/spell.rc)
   sql            vile-sql-filt        SQL
   tags           vile-tags-filt       tags files (see ctags(1)).
   tbl            vile-tbl-filt        vile's modetbl and cmdtbl files
   tc             vile-tc-filt         termcap and printcap files
   tcl            vile-tcl-filt        tcl/tk scripts
   tex            vile-latex-filt      TeX
   texi           vile-texi-filt       texinfo
   ti             vile-ti-filt         terminfo files
   txt            vile-txt-filt        various flavors of text files
   vile           vile-vile-filt       vile and vim macros
   vlog           vile-vlog-filt       verilog
   wbt            vile-wbt-filt        WinBatch
   xml            vile-html-filt       XML, DocBook
   xpm            vile-xpm-filt        X resource files
   xres           vile-xres-filt       X resource files
   xs             vile-xs-filt         Perl extension source files
   yacc           vile-yacc-filt       yacc and bison

   As you might expect, when the "--with-builtin-filters" option is selected,
   all of the internal filters listed above are bound into the editor. "Hey,
   wait a minute", you say, "I'll never use some of those filters--not in a
   hundred years." In that case, use this configure syntax:

         --with-builtin-filters="<filter_list>"

   For example:

         ./configure --with-cflags=-O2 \
                     --with-builtin-filters="awk c key lex m4 perl sed tags
                     diff html mail make pl rcs sh sql tbl tcl txt vile yacc"
         make
         make install

   The above commands:

     * compile vile [1],
     * compile and link 21 filters into the final editor image,
     * create the remaining, non-builtin filters as external executable
       images, and
     * copy the editor and external filters to an to an install tree [2].

   Assuming the editor's startup file initiates syntax coloring [3], then at
   vile run time, the macro file filters/filters.rc preferentially selects
   and executes internal filters when coloring a supported language or file
   format. If a required internal filter is not available, filters.rc starts
   a pipe and applies color attributes via the corresponding external filter
   listed in the table above.

   [1] Or xvile if you prefer. See next topic.
   [2] Described below in the topic "Installing x(vile)".
   [3] Refer to the topics "Color basics" and "Syntax coloring" in vile.hlp


Building xvile
--------------
   You must decide which version of xvile you want to build. To a certain
   degree this decision may be forced upon you by which libraries you have on
   your machine. There are three different versions you can build.

    1. X toolkit version: This version uses only the X toolkit to implement
       scrollbars and the window resize grips (meaning _vile_ windows, not X
       windows). As a consequence, it should only require the X toolkit
       library (-lXt) and the Xlib library (-lX11). (Don't worry if you don't
       know what these are or where these are; the configuration script will
       probably be able to find them.) The scrollbars in this version look
       much like those found in a standard xterm. We recommend that you try
       this version out first as it is superior in some respects to the other
       versions which use fancy widget sets. To configure this version, enter
       the following command:

         ./configure --with-screen=x11

       A minor variation using the Athena widgets supports menus:

         ./configure --with-screen=Xaw

       Two other variations on the Athena widgets are provided:

         ./configure --with-Xaw3d

       to link with Xaw 3d library

         ./configure --with-neXtaw

       to link with neXT Athena library. There's little functional difference
       between the three versions of Athena libraries, they provide different
       appearance. You can also configure with the corresponding scrollbars
       from the Athena library (though we are not as satisfied with their
       performance, particularly with resizing):

         ./configure --with-Xaw-scrollbars

       to use Xaw scrollbars rather than our own (applies to all variations
       of Athena library). You can also use Kevin's dragging/scrolling logic
       with the Athena library:

         ./configure --with-drag-extension

    2. Motif version: This version uses the Motif widget set to implement the
       scrollbars and (vile) window resize pane. To configure the Motif
       version, enter one of the following commands (several variations are
       recognized for each screen value to simplify integration with other
       scripts):

         ./configure --with-screen=motif
         ./configure --with-screen=Xm

   The Athena and Motif versions support a menubar, with pulldown menus. The
   configure option --enable-colored-menus compiles-in resource values which
   simplify coloring the menubar and menus with the same foreground and
   background colors. The corresponding resource values are menuForeground
   and menuBackground.

   There are also options for configuring the icon used, using option values:

   --with-xpm
           use this to check for, and use the Xpm library which supports
           colored options (".xpm" in contrast to the monochrome ".xbm").

   --with-icon-name=XXX
           allows you to override the icon name. Normally this is the "vile"
           icon, which shows a representation of an editing screen. The other
           choices are
              * --with-icon-name=pumpkin
              * --with-icon-name=sink

           There is a "mini" icon used in a few special cases which consists
           only of the tilde's from the "vile" icon. That is unaffected by
           this configure option.

   --with-pixmapdir=XXX
           specify the directory in which to install pixmaps, e.g.,
           /usr/share/pixmaps.

           The special value "auto" tells the configure script to check for
           the existence of (fairly standard) locations.

   --with-icondir=XXX
           specify the directory in which to install icons for desktop, e.g.,
           /usr/share/icons.

           The special value "auto" tells the configure script to check for
           the existence of (fairly standard) locations.

   --with-icon-theme=XXX
           install icons into desktop theme (default "hicolor"). Vile
           provides ".svg" and ".png" flavors of the icons which are used for
           this option. If you use the icon-theme option, it is still a good
           idea to not suppress the pixmap feature due to inconsistencies and
           gaps in the support provided by the desktop configurations.


Installing (x)vile
------------------
   Installation of (x)vile is simple. Obtain the appropriate privileges
   (become superuser if necessary), and enter the following command:

         make install

   If you have ever installed an older version of vile, you should probably
   check to be sure the old help files are gone. They used to go to a
   different place (by default) than they do now. It can be most confusing to
   use an older version of the help file with a newer version of the program,
   and unfortunately, older help files didn't have version numbers.

   By default, (x)vile and the script "vile-pager" are installed in
   /usr/local/bin. Other editor components are stored in these directories:

   component               install dir
   vile.hlp                /usr/local/share/vile
   vile.1 (man page)       /usr/local/man/man1
   syntax coloring filters [note 1]
   coloring keyword files  /usr/local/share/vile
   various macro files     /usr/local/share/vile

   Note 1: the value of the environment variable VILE_LIBDIR_PATH specifies
   where configure installs external coloring filters. If unset, configure
   defaults to /usr/local/lib/vile.

   We realize that not everyone has superuser privileges on the machines on
   which they wish to build (x)vile. If you lack superuser access or write
   access to /usr/local, you will want to change the installation location.
   You may do so by using the --prefix option to "configure". Suppose you
   wish to have xvile installed in $HOME/bin (your home bin directory). You
   would issue the following commands:

     ./configure --with-screen=x11 --prefix=$HOME
     make install

   Here are other useful options for configuring xvile:

   --with-app-defaults=DIR directory in which to install resource files (default: EPREFIX/lib/X11/app-defaults)
   --with-icondir=DIR      directory in which to install icons (default: EPREFIX/share/pixmaps)
   --disable-desktop       disable install of X desktop files

   The file INSTALL has more information on installation and on configure's
   --prefix option. If you don't feel like rebuilding (likely), you can also
   edit the makefile and change the "prefix", "bindir", or "libdir"
   definitions--but remember that your changes will be lost the next time
   configure is run.


Building in a separate directory
--------------------------------
   If you are building (x)vile for several machines or want to perhaps
   simultaneously build and try out the various versions of xvile, you will
   probably want to configure (x)vile to build in a directory different from
   where the source resides. This requires that you have make program which
   correctly uses the VPATH variable. GNU make does this well, others may or
   may not.

   Suppose that the source resides in vile-src. At the same level as
   vile-src, you might perhaps create a directory called vile-x11-sunos to
   indicate that you are building xvile on a platform running sunos. You
   would then cd into this directory and issue the following configuration
   command:

         ../vile-src/configure --with-screen=x11

   Another directory at the same level as vile-src might be named vile-sunos
   to indicate that you are building vile on a platform running sunos. After
   you cd into this directory, you'd then issue the following command to
   configure ordinary vile.

         ../vile-src/configure

   The "make" step in each case is the same as described above; you simply
   issue the command:

         make

   to finish making (x)vile.

   This process is described in more formally in the INSTALL document. As
   described there, you will need to use a version of "make" which supports
   the VPATH variable. And it must support it _correctly_. Again, GNU make
   does this. A lot of older "make"s don't.


Building Versioned Executables
------------------------------
   Normally vile is installed without renaming it. But the configure script
   supports these options, which allow you to rename the program:

   --program-prefix=PREFIX            prepend PREFIX to installed program names
   --program-suffix=SUFFIX            append SUFFIX to installed program names
   --program-transform-name=PROGRAM   run sed PROGRAM on installed program names
   --with-symlink=XXX      make symbolic link to installed application

   In particular, the --with-symlink option is used to install executables
   that are named according to vile's version, e.g., vile-9.7za, vile-9.7zb,
   etc., with a symbolic link pointing to the most recently installed
   executables. This allows you to install successive releases of vile, and
   easily switch between them (provided that the associated macros are
   compatible).


Locale Support
--------------
   There are two parts to locale support:

   --with-locale           use i18n support for character-types
   --with-iconv            use iconv() support for character-types
   --with-libiconv-prefix=DIR
                           search for libiconv in DIR/include and DIR/lib

   The --with-locale option provides the basic portable support for different
   character types. It is enabled by default since only rather old systems
   lack support for these functions. (Some older systems have the functions
   but only a buggy implementation; it is not simple to make the configure
   script aware of those).

   The --with-iconv option checks for functions that vile can use to
   facilitate editing UTF-8 text on devices which do not display UTF-8, as
   well as work with UTF-8 files which are largely compatible with 8-bit
   encoding.

   Without the iconv option, vile can still work with UTF-8, but the support
   for non-UTF-8 encoding is focused on ISO-8859-1.


Other Compile-Time Options
--------------------------
   Aside from the screen type, most functionality in vile is controlled by
   the "OPT_" #ifdef's in the estruct.h file. Some of the more useful ones
   (or those that require manipulating the makefile) are also provided as
   configure options:

   --with-exec-macros=N    specify count of numbered macros  (anachronism)
   --with-perl             enable use of Perl as an extension language


Testing/Development Options
---------------------------
   Several other options appear in the configure script's "--help" message.
   They are used to support testing and development, by building various
   debug versions of vile. These include:

   --enable-warnings       test: turn on GCC compiler warnings
   --disable-echo          test: display "compiling" commands (default: on)
   --disable-extensions    test: build only core functions (default: on)
   --disable-rpath-hack    don't add rpath options for additional libraries
   --disable-shell         test: disable shell/external commands (default: on)
   --with-dbmalloc         test: use Conor Cahill's dbmalloc library
   --with-dmalloc          test: use Gray Watson's dmalloc library
   --with-no-leaks         test: free permanent memory, analyze leaks
   --with-trace            test: turn on debug-tracing

   The dbmalloc and dmalloc libraries are similar, checking for memory leaks
   and related malloc/free problems. Both have limitations, so we use both,
   as well as other tools such as Purify and ElectricFence, according to the
   problem.

   The --with-no-leaks option compiles in code that frees all of the
   permanently allocated memory on exit. This greatly simplifies the task of
   analyzing memory leaks.

   The --with-trace option turns on debug traces that go to the Trace.out
   file. Since vile is a fullscreen program, it is not useful to write
   messages to the screen. (The OPT_HEAPSIZE option is an exception; you may
   be amused by it).

   The --with-warnings option applies mostly to compiles with GCC, since it
   is available across several platforms. We build with all available
   compilers, but their warnings options are not consistent.

   Because the echoed commands in the makefile are long, the --disable-echo
   option is provided to shorten the commands, making it easy to see the
   warnings.

   The --disable-extensions and --disable-shell options are for testing.
   Disabling extensions produces a smaller program, essentially the core of
   vile (no macros), which is a workable editor. You may wish to build vile
   without shell support, but perhaps not (ymmv).

   The --disable-rpath-hack option is useful for packagers, who may not wish
   the executable to be bound to a particular library path from their build
   environment.

-- (generated by make-hlp.pl from config.html(1.23))
-- vile:txtmode fillcol=78
-- $Id: config.doc,v 1.39 2021/01/01 12:41:09 tom Exp $