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.
To build vile, enter the following command from your shell:
If you'd like to examine makefile and config.h prior to making, split these steps up as follows:
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:
Or, this can be done when running the configure script instead -- try:
CFLAGS=-O2 ./configure (sh, ksh, bash)
(setenv CFLAGS -O2 ; ./configure) (csh)
Then again, a configure script argument is shell-agnostic:
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)
(setenv CC cc ; ./configure) (csh)
Likewise, extra link libraries can be added by setting them in LIBS before running configure.
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:
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.,
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".
There are several choices, listed here in their order of capabilities:
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:
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.
There are several choices, again listed in
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.
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:
The "DOS" and "Windows" choices are comparable in functionality to the executables built using Visual C++.
vile supports UTF-8 in two ways:
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.
Adding syntax coloring to the editor can be simple or not.
Maximally efficient syntax coloring can be selected by specifying this configure command line:
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.
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.
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 Name||External Filter Name||Colors These Language(s)/Files|
|as||vile-as-filt||GNU assembler (x86)|
|asm||vile-asm-filt||Microsoft ASM (x86)|
|basic||vile-basic-filt||basic and visual basic (vb, vbs)|
|bat||vile-bat-filt||Windows .bat files|
|cfg||vile-cfg-filt||lynx config files|
|conf||vile-conf-filt||ordinary config files|
|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|
|esql||vile-esql-filt||embedded SQL with C/C++.|
|fdl||vile-fdl-filt||forms definition language|
|info||vile-info-filt||GNU info files|
|ini||vile-ini-filt||Windows .ini, .reg, .vbp files|
|key||vile-key-filt||vile .keyword files|
|lex||vile-lex-filt||flex and lex|
|m4||vile-m4-filt||autoconf and m4|
|make||vile-make-filt||make and nmake files|
|mcrl||vile-mcrl-filt||mCRL/mCRL2 modeling language.|
|mms||vile-mms-filt||VMS make files|
|pot||vile-pot-filt||gettext (.po) files|
|rc||vile-rc-filt||Windows resource (.rc) files|
|rpm||vile-rpm-filt||RPM .spec files|
|rtf||vile-rtf-filt||Rich Text Format|
|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)|
|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|
|txt||vile-txt-filt||various flavors of text files|
|vile||vile-vile-filt||vile and vim macros|
|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:
./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:
Assuming the editor's startup file initiates syntax coloring , 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 corresponsing external filter listed in the table above.
 Or xvile if you prefer. See next topic.
 Described below in the topic "Installing x(vile)".
 Refer to the topics "Color basics" and "Syntax coloring" in vile.hlp
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.
A minor variation using the Athena widgets supports menus:
Two other variations on the Athena widgets are provided:
to link with Xaw 3d library
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):
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-screen=motif ./configure --with-screen=Xm
The Athena and Motif versions support a menubar, with pulldown
menus. The configure option
compiles-in resource values which simplify coloring the menubar
and menus with the same foreground and background colors. The
corresponding resource values are
There are also options for configuring the icon used, using option values:
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.
The special value "auto" tells the configure script to check for the existence of (fairly standard) locations.
The special value "auto" tells the configure script to check for the existence of (fairly standard) locations.
Installation of (x)vile is simple. Obtain the appropriate privileges (become superuser if necessary), and enter the following command:
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:
|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.
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:
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.
The "make" step in each case is the same as described above; you simply issue the command:
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.
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
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).
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
--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).
--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.
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
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:
--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 --with-warnings test: turn on GCC compiler warnings
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.