home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 5 Edit / 05-Edit.zip / vile-src.zip / vile-8.1 / doc / config.doc next >
Text File  |  1997-12-17  |  12KB  |  311 lines
  1. README.CFG
  2. ----------
  3.  
  4. This file describes the steps which are needed to configure and make either
  5. vile or xvile.  See the file README for a blurb on what (x)vile is and how
  6. great it is :-).  The file INSTALL contains generic information on the
  7. process of configuring and building programs which (more or less) conform
  8. to the GNU coding standards.  You might want to consult that document for
  9. more information.
  10.  
  11.  
  12. Building vile
  13. -------------
  14.  
  15. To build vile, enter the following command from your shell:
  16.  
  17.     ./configure; make
  18.  
  19. If you'd like to examine makefile and config.h prior to making, split these
  20. steps up as follows:
  21.  
  22.     ./configure
  23.     make
  24.  
  25. If you are unfortunate enough to be running on a platform in which some
  26. part of the above process does not work perfectly, you might well want to
  27. modify makefile to add references to obscure libraries or non-standard
  28. library locations.
  29.  
  30.     [ At least one version of bash running on Linux (and perhaps other)
  31.     systems will cause the configure script to produce invalid results. 
  32.     Specifically, if you're running version 1.14.3 of bash consider
  33.     upgrading to a newer one.  ]
  34.  
  35. Modifying makefile is not recommended because your changes will be lost
  36. should you run configure again.  Many configuration options can be
  37. set externally to the configure script or the makefile.  For instance,
  38. if you'd like to change some of the flags passed to the C compiler, try
  39. doing it like this:
  40.  
  41.     make CFLAGS=-O2
  42.  
  43. Or, this can be done when running the configure script instead -- try:
  44.     CFLAGS=-O2 ./configure            (sh, ksh, bash)
  45. or:
  46.     (setenv CFLAGS -O2 ; ./configure)    (csh)
  47.  
  48. If you need to suppress your optimizer (which is invoked as -O by default),
  49. because it's known to be buggy, use CFLAGS=" ".  [ One combination
  50. thought to be buggy is AIX 3.2.5 with gcc 2.6.0.  ]
  51.  
  52. The configure script will favor using gcc on your system if available.  This
  53. is usually fine, but if gcc was not installed correctly (or your environment
  54. isn't quite right), it can be disastrous.  You can override the choice
  55. of compiler with:
  56.     CC=cc ./configure        (sh, ksh, bash)
  57. or:
  58.     (setenv CC cc ; ./configure)    (csh)
  59.  
  60. Likewise, extra link libraries can be added by setting them in LIBS before
  61. running configure.
  62.  
  63.  
  64. Screen Types
  65. ------------
  66.  
  67. Vile is configured and built with a terminal driver.  At this time, only
  68. one driver is built with vile at a time.  Some other editors attempt to
  69. combine more than one driver in the default configuration, making the
  70. resulting program much larger and slower.  We will ultimately modify vile
  71. to support multiple drivers, but the default configuration will be the
  72. smallest and fastest.
  73.  
  74. Use the configure script's "--with-screen" option to specify the driver
  75. type, e.g.,
  76.  
  77.     ./configure --with-screen=tcap
  78.  
  79. The default configuration for vile uses termcap (or terminfo, depending
  80. what your system has available).  The configuration script tests several
  81. possibilities.  Your system may have more than one library to link against,
  82. e.g., on Linux you may have both termcap and ncurses (a terminfo-based
  83. system).  If you wish to use color, you are generally better off using
  84. terminfo, since termcap descriptions usually are limited to a fixed size,
  85. and some features are omitted.  To tell the configure script to link
  86. against the ncurses library (but still using the basic termcap/terminfo
  87. driver), type
  88.  
  89.     ./configure --with-screen=ncurses
  90.  
  91. A much less capable driver uses builtin ANSI escape sequences:
  92.  
  93.     ./configure --with-screen=ansi
  94.  
  95.  
  96. Building xvile
  97. --------------
  98.  
  99. You must decide which version of xvile you want to build.  To a certain
  100. degree this decision may be forced upon you by which libraries you have
  101. on your machine.  There are three different versions you can build.
  102.  
  103. 1) X toolkit version: This version uses only the X toolkit to implement
  104. scrollbars and the window resize grips (meaning _vile_ windows, not X
  105. windows).  As a consequence, it should only require the X toolkit library
  106. (-lXt) and the Xlib library (-lX11).  (Don't worry if you don't know what
  107. these are or where these are; the configuration script will probably be
  108. able to find them.)  The scrollbars in this version look much like those
  109. found in a standard xterm.  We recommend that you try this version out
  110. first as it is superior in some respects to the other versions which use
  111. fancy widget sets.  To configure this version, enter the following command:
  112.  
  113.     ./configure --with-screen=x11
  114.  
  115. A minor variation using the Athena widgets supports menus:
  116.  
  117.     ./configure --with-screen=Xaw
  118.  
  119. Two other variations on the Athena widgets are provided:
  120.  
  121.     ./configure --with-Xaw3d
  122.  
  123. to link with Xaw 3d library
  124.  
  125.     ./configure --with-neXtaw
  126.  
  127. to link with neXT Athena library.  There's little functional difference
  128. between the three versions of Athena libraries, they provide different
  129. appearance.  You can also configure with the corresponding scrollbars from
  130. the Athena library (though we are not as satisfied with their performance,
  131. particularly with resizing):
  132.  
  133.     ./configure --with-Xaw-scrollbars
  134.  
  135. to use Xaw scrollbars rather than our own (applies to all variations of
  136. Athena library).  You can also use Kevin's dragging/scrolling logic with
  137. the Athena library:
  138.  
  139.     ./configure --with-drag-extension
  140.  
  141. 2) Motif version:  This version uses the Motif widget set to implement
  142. the scrollbars and (vile) window resize pane.  To configure the Motif
  143. version, enter one of the following commands (several variations are
  144. recognized for each screen value to simplify integration with other
  145. scripts):
  146.  
  147.     ./configure --with-screen=motif
  148.     ./configure --with-screen=Xm
  149.  
  150. 3) OpenLook version:  Uses the OpenLook widgets to implement scrollbars. Since
  151. OpenLook lacks a pane widget, resizing (vile) windows is pretty cheesy.  Still,
  152. if you are running olwm or olvwm, you might well want to run this version
  153. so that xvile will look the same as your other applications.
  154.  
  155.     ./configure --with-screen=openlook
  156.     ./configure --with-screen=Xol
  157.  
  158. After configuration, you may look at the makefile or config.h if you wish. You
  159. can finish making xvile by entering the following command:
  160.  
  161.     make
  162.  
  163. On some systems it seems to be sometimes necessary (?) to have X_LIBS set
  164. to -static prior running configure, i.e, use either:
  165.  
  166.     X_LIBS=-static ./configure --with-screen=openlook
  167.  
  168. for sh, ksh, and bash.  Or:
  169.  
  170.     (setenv X_LIBS -static ; ./configure --with-screen=openlook)
  171.  
  172. for csh and tcsh.
  173.  
  174.  
  175. Installing (x)vile
  176. ------------------
  177.  
  178. Installation of (x)vile is simple.  Obtain the appropriate privileges (become
  179. superuser if you have to), and enter the following command:
  180.  
  181.     make install
  182.  
  183. If you have ever installed an older version of vile, you should probably
  184. check to be sure the old help files are gone.  They used to go to a
  185. different place (by default) than they do now.  It can be most confusing
  186. to use an older version of the help file with a newer version of the
  187. program, and unfortunately, older help files didn't have version numbers.
  188.  
  189. We realize that not everyone has superuser privileges on the machines on
  190. which they wish to build (x)vile.  By default, the executables will be
  191. installed in /usr/local/bin.  vile.hlp will be installed in /usr/local/lib. 
  192. vile.1 (the manual page) will be installed in /usr/local/man/man1.  If you
  193. lack superuser access or write access to /usr/local, you will want to
  194. change the installation location.  You may do so by using the --prefix
  195. option to "configure".  Suppose you wish to have xvile installed in
  196. $HOME/bin (your home bin directory).  You would issue the following
  197. configuration command:
  198.  
  199.     ./configure --with-screen=x11 --prefix=$HOME
  200.  
  201. The file INSTALL has more information on installation and on the --prefix
  202. option to "configure".  (If you don't feel like rebuilding (likely), you
  203. can also edit the makefile and change the "prefix", "bindir", or "libdir"
  204. definitions -- remember that your changes will be lost next time you run
  205. configure.
  206.  
  207.  
  208. Building in a separate directory
  209. --------------------------------
  210.  
  211. If you are building (x)vile for several machines or want to perhaps
  212. simultaneously build and try out the various versions of xvile, you will
  213. probably want to configure (x)vile to build in a directory different from
  214. where the source resides.  This requires that you have make program which
  215. correctly uses the VPATH variable.  GNU make does this well, others may
  216. or may not.
  217.  
  218. Suppose that the source resides in vile-src.  At the same level as
  219. vile-src, you might perhaps create a directory called vile-x11-sunos to
  220. indicate that you are building xvile on a platform running sunos.  You
  221. would then cd into this directory and issue the following configuration
  222. command:
  223.  
  224.     ../vile-src/configure --with-screen=x11
  225.  
  226. Another directory at the same level as vile-src might be named vile-sunos
  227. to indicate that you are building vile on a platform running sunos. After
  228. you cd into this directory, you'd then issue the following command to
  229. configure ordinary vile.
  230.  
  231.     ../vile-src/configure
  232.  
  233. The "make" step in each case is the same as described above; you simply
  234. issue the command:
  235.  
  236.     make
  237.  
  238. to finish making (x)vile.
  239.  
  240. This process is described in more formally in the INSTALL document.  As
  241. described there, you will need to use a version of "make" which supports
  242. the VPATH variable.  And it must support it _correctly_.  Again, GNU make
  243. does this.  A lot of older "make"s don't.
  244.  
  245.  
  246. Other Compile-Time Options
  247. --------------------------
  248.  
  249. Aside from the screen type, most functionality in vile is controlled by the
  250. "OPT_" #ifdef's in the estruct.h file.  Some of the more useful ones (or
  251. those that require manipulating the makefile) are also provided as configure
  252. options:
  253.  
  254.   --with-exec-macros=N    specify count of numbered macros
  255.   --with-perl             enable use of Perl as an extension language
  256.  
  257.  
  258. Testing/Development Options
  259. ---------------------------
  260.  
  261. Several other options appear in the configure script's "--help" message.
  262. They are used to support testing and development, by building various
  263. debug versions of vile.  These include:
  264.  
  265.   --disable-echo          test: display "compiling" commands (default: on)
  266.   --disable-extensions    test: build only core functions (default: on)
  267.   --disable-shell         test: disable shell/external commands (default: on)
  268.   --with-dbmalloc         test: use Conor Cahill's dbmalloc library
  269.   --with-dmalloc          test: use Gray Watson's dmalloc library
  270.   --with-no-leaks         test: free permanent memory, analyze leaks
  271.   --with-trace            test: turn on debug-tracing
  272.   --with-warnings         test: turn on GCC compiler warnings
  273.  
  274. The dbmalloc and dmalloc libraries are similar, checking for memory leaks
  275. and related malloc/free problems.  Both have limitations, so we use both,
  276. as well as other tools such as Purify and ElectricFence, according to the
  277. problem.
  278.  
  279. The --with-no-leaks option compiles in code that frees all of the
  280. permanently allocated memory on exit.  This greatly simplifies the task of
  281. analyzing memory leaks.
  282.  
  283. The --with-trace option turns on debug traces that go to the Trace.out
  284. file.  Since vile is a fullscreen program, it is not useful to write
  285. messages to the screen.  (The OPT_RAMSIZE option is an exception; you may
  286. be amused by it).
  287.  
  288. The --with-warnings option applies mostly to compiles with GCC, since it is
  289. available across several platforms.  We build with all available compilers, but
  290. their warnings options are not consistent.
  291.  
  292.     [ However, --with-warnings also turns on checks for missing prototypes,
  293.     assuming that an ANSI or Posix prototype is better than none (e.g., for
  294.     SunOS 4.x).  However, this may result in a config.h too long for your
  295.     sed program to handle.  GNU sed works properly.  An alternative is the
  296.     td_config utility bundled with Tom's directory editor. ]
  297.  
  298. Because the echoed commands in the makefile are long, the
  299. --disable-echo option is provided to shorten the commands, making it easy to
  300. see the warnings.
  301.  
  302. The --disable-extensions and --disable-shell options are for testing. 
  303. Disabling extensions produces a smaller program, essentially the core of
  304. vile (no macros), which is a workable editor.  You may wish to build vile
  305. without shell support, but perhaps not (ymmv).
  306.  
  307.  
  308. ------------------------
  309. $Header: /usr/build/vile/vile/doc/RCS/config.doc,v 1.1 1997/12/17 11:16:54 tom Exp $
  310. ------------------------
  311.