http://invisible-island.net/vile/vile-toc

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:

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:

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.