This HOWTO tries to describe Turbo Vision: - introduction & requirements - getting & installation - bug reporting & fixing

TurboVision-HOWTO
=================
by Laurynas Biveinis <[email protected]>

Contents:
1. Introduction
2. Requirements
3. What to download
4. Installation
5. Bugs
6. Info

1. Introduction
~~~~~~~~~~~~~~~

   In this HOWTO I'll try to describe Turbo Vision class library - why you
might want to use it, what to download, how to install, how to report bugs, and
most important - how to fix them.
   So, what's Turbo Vision (TV in short)? It is C++ class library for creating
nice and intuitive textual user's interface. You can create menus, windows,
dialog boxes with buttons, input lines, scroll bars and much, much more with TV
help. It is so-called "event driven" library, it means that your program does
not execute (let's simplify) line-by-line. Instead of it, you have to write to
write routines which respond to particular events, such as key presses or mouse
clicks. At first, it could be hard to understand for programmer without any
windowed environment programming experience, but once mastered, it's a powerful
tool. This HOWTO will describe Turbo Vision's port to DJGPP.

2. Requirements
~~~~~~~~~~~~~~~

   Of course I assume you have DJGPP installation set up correctly and running.

   Necesarry:

   - C++ and Object-Oriented Programming (OOP) knowledge.
         Turbo Vision is an OO-library (well, almost...) using many
      C++ features such as inheritance and virtual functions so you have to
      know them and OOP.

   - GCC 2.7.x, GCC 2.8.x, EGCS 1.x or GCC 2.95.x for sources of library.
         I recommend using GCC 2.95.x (except for Turbo Vision 1.0.8), if not
      available - EGCS 1.1.2. They produce better code when compared with
      earlier GCC versions. I'm not aware if Pentium GCC (PGCC) works. Well,
      it should.

   - GNU Gettext
        If you're lazy or don't want have your programs translated to other
      languages, you can live without it, but it's an untested way. You can
      get it from v2gnu directory in your favorite SimtelNet mirror, file
      gtxt035b.zip.

   For makefiles you will need:

   - GNU Make or RHIDE 1.4.7+
        It's your choice. SET and I use GNU Make v3.77 and haven't tested
      any other versions nor makes. If you succeed to use anything else, let
      SET and me know. GNU Make port to DJGPP is available in v2gnu/mak377b.zip
      in any SimtelNet mirror. If you use use RHIDE, get latest beta version
      (currently 1.4.7.7). Release 1.4 will not work, just crash.

   For using GNU style `configure' scripts (see below):

   - GNU Fileutils
        For `configure' script and `make install' target. v2gnu/fil316b.zip in
      SimtelNet.

   - GNU Shellutils
        For `configure' script. v2gnu/shl112b.zip in SimtelNet.

   - Perl
       For some scripts. You can live without this one.

3. What to download
~~~~~~~~~~~~~~~~~~~

   At first I recommend to visit TV's port to DJGPP home page,
http://tvision.sourceforge.net/#ddjgpp and check which
version is newest. Then get it from there or from any SimtelNet mirror, file
v2tk/tv10xs.zip for source distribution (x is replaced by TV version
patchlevel). The  latest version at the time of this writing was 1.0.10.
Also, you must get GNU Gettext. You can get binaries from v2gnu/gtxt035b.zip,
source v2gnu/gtxt035s.zip. If you are using version 0.10.35 and get strange
errors about headers, re-download version 0.10.35 from SimtelNet - the latest
upload fixes some grave problems. Binaries should be OK, building it from
sources works too. One more option - do to get GNU Gettext at all, however
this way is untested and not recommended.

4. Installation
~~~~~~~~~~~~~~~

   1) Install GNU Fileutils, shellutils, Perl, if you don't have them installed
   but plan to use `configure' script.

   1) Installation of GNU Gettext binaries -
       simply unextract zip to your DJGPP directory tree, preserving directories.

   2) Unpack Turbo Vision sources -
      unextract TV zip into your DJGPP directory tree, preserving directory
   structure.

   3) Compile Turbo Vision sources.
      Starting from TV version 1.0.9, there are two options for compilation and
   installation -
      3.1) If you are used to do GNU style `configure', 'make',
        'make install', and have installed all required tools (see above),
        then you can simply go to <your DJGPP directory>/contrib/tvision/djgpp
        directory and run `configure', `make', `make install' here.
      3.2) Old way for those who do not have installed all required tools -
        go to the <your DJGPP directory>/contrib/tvision/djgpp directory. You
        have two choices: 1) run "make" here and it will compile the library
        for you. Also you can edit makefile and adjust some settings if you
        want. 2) Run RHIDE in directory above. It will open project file there
        and all you have to do in order to compile TV is hit F9.
   *Warning* - do not compile TVision version 1.0.8 (earlier and later ones
   are OK) with GCC 2.95.x! This TV version contains some new assembler code,
   which is not permitted by GCC 2.95.x. Earlier versions of GCC/EGCS should
   compile it smoothly. This problem is fixed in TVision starting from version
   1.0.9.

   4) Prepare library for using.
      This means make its library and include files visible to your programs.
   If you have used `configure', `make', `make install', then you already have
   installed library in <DJGPP directory>/lib and its headers in
   <DJGPP directory>/include/rhtvision.
   Other way - you can create environment variable TVISION pointing to the base
   of TV installation, e.g.
   TVISION=C:/DJGPP/contrib/tvision
   Then you can access TV include files saying $(TVISION)/include and library -
   $(TVISION)/djgpp. If you want to make compiler automatically see these paths,
   edit your djgpp.env file:
   - add "+TVISION=%DJDIR%/contrib/tvision" near the beginning of file.
   - in the section [cpp] find line beginning with "CPLUS_INCLUDE_PATH=" and
     append ";%TVISION%/include" to the end of it.
   - in the section [gcc] find line beginning with "COMPILER_PATH=" and
     append ";%TVISION%/djgpp" to the end of it.
   - Done!

5. Bugs
~~~~~~~

   If you find a bug, send a description of it to SET <[email protected]>.
Please do not send it to me, because I'll have to resend it to SET anyway.
(Well, maybe I'll take a look). One more thing - bug fixes are more prefered
than bug reports :) To send a bug fix, make "diff -u -r" between your current
TVision directory tree and unchanged latest TVision version directory tree.
E.g.: diff -u -r tvision.110 tvision > patch.diff. Again, please send it to
SET <[email protected]>, not to me. And please describe what does your
patch do.

4. Info
~~~~~~~

This HOWTO was written by Laurynas Biveinis <[email protected]> and reviewed
by SET.
Thanks to:
  - Salvador Eduardo Tropea (SET) <[email protected]> for maintaining TV
port to DJGPP and reviewing this HOWTO.
You can distribute this HOWTO freely, but please contact me if you want to
make any changes.

Small changes history:

1.3 -

	* updated current TV version to 1.0.10
	* updated current GNU Gettext version to 0.10.35
	* updated current RHIDE version to 1.4.7.7
	* remove references to TV upgrade patches

1.2 -
    * updated current TV version to 1.0.9
    * added new info to `requirements' section
    * added new info about compiling TV 1.0.9

1.1 -
    * updated current TV version to 1.0.8
    * added info about compiling 1.0.8 with GCC 2.95.x

1.0 -
  First public version, updates according to SET:
    * removed info about TV binaries
    * Added info about RHIDE
    * corrected typos.

1.0 Beta -
    * first version, sent to SET for review

Last update 2000.11.13.