The V C++ GUI Framework User Guide:Installing V

=General Installation Notes= I believe that V is one of the easiest to program GUI frameworks you will find. However, because it has been designed to work on several platforms, each with differing file systems and C++ compilers, getting a working version of V takes a little effort.

Please remember that V is a free package, and is being done completely by volunteers. I am paying for the ObjectCentral web site that is the home of V out of my own pocket. Supporting a program like V takes a lot of time and effort. Mostly I want to spend that effort on improving the library itself. Thus, my philosophy on distribution is to keep the number of downloadable files to a minimum. For the core (X LessTif and MS-Windows) distribution, I've chosen to use gzipped tar files. If you have Linux or other Unix flavour, this is the natural format. If you use MS-Windows, then you can use the popular WinZip program which supports .tgz files, or download Windows versions of tar and gunzip from the ObjectCentral ftp site.

The OS/2 and X gtk version are built by the volunteers that did those ports. I try to let them do what is easiest and best for them.

So, please take the time to read this section carefully. It should have the details you need to get a working version of V for almost any supported platform. If you think there would be a better way, I'd appreciate any volunteer effort you'd like to put into a more automated process. I am somewhat limited on disk space available at ObjectCentral, however. Now to the details...

Beginning with V Version 1.21, the V distribution will consist of several parts.

As of Version 1.21, the documentation is maintained only in html format. The latest version of the full html source of the documentation is called vref.html.tar.gz. A printable version using Adobe Acrobat PDF format is also available. The PDF version has been automatically generated from the HTML source, and is called vref.pdf. V has been designed to be easily installed on many platforms. This document describes some of the details you will need to know to install V on your system. This installation guide covers the distributions of V used by the most users. Some platforms are not explicitly covered, but there should be enough general information here to get you started. It has been my policy to distribute V only in source format, and not include precompiled versions of the library or applications. There are two reasons for this. First, there are a bunch of C++ compilers out there, and they usually don't work together. It would take just too much effort to try them all. Second, I think getting V to compile with your compiler on your system is a good exercise. If you can get that far, then you should be able to produce a V application with few problems.However, that said, beginning with Version 1.21, the distribution will also contain ready to use compiled versions of the library and V utility applications for the platforms and compilers I have easy access to. Initially, these will include Mingw32 egcs, and perhaps Borland C++ for MS-Windows, and an elf binary for Linux systems. The distributions will be split into three parts: executables for various V utility programs, the V include files, and finally the V library files for each compiler. See the ObjectCentral ftp site for latest binary versions. Instructions for installation of the binary versions are included later in this page.
 * Full source. The complete source of the V Library for MS-Windows and X Windows will be found on vsrc-1.22.tar.gz, a gzipped tar file suitable for either MS-Windows or X platforms such as Linux. The full source contains all the source and the make files and project files normally needed to get V compiled on your machine. Use the standard Linux/Unix gunzip and tar programs to extract the file. MS-Windows versions of these are available on ObjectCentral ftp site. WinZip also will extract gzipped tar files.
 * Documentation
 * Binary distributions

General Installation Philosophy
I think it is appropriate to discuss my general philosophy about the distribution of V, and how Version 1.21 represented a major change. First, it is important to remember that the distribution of V is essentially a one person effort. The X Athena and Motif versions, and the Windows WIN32 versions, as well as the documentation, are currently completely being done by me, Bruce Wampler. The OS/2 is the responsibility of Jon Hacker, and the X gtk version has been done by Sven Verdoolaege (skimo). Thus, there are really three distributions of V.

Nevertheless, I'm still the main focal point of V, and am responsible for the main distribution, and approval of the other releases. Thus, some of the decisions about the distribution have been made to minimize the time I spend on distribution, and maximize the time I spend on adding features. Thus, I don't use an Install program on MS-Windows, and haven't RPM packaged V for Linux. I'd more than welcome any volunteers to do anything to make installation simpler.

Until the 1.21 release, V had been strictly a source code distribution. I've finally decided that is not the best decision. So, beginning with this version, I will provide pre-compiled binaries for several major compilers and platforms. If you successfully build a version of V for one that I haven't provided, please let me know, and I will include your version on the distribution site.

Because of the history as a source only distribution, and because many V users will still have to compile it, this document will still be heavily oriented to telling you how to compile V on your system. If you are lucky enough to use a compiler supported by a binary distribution, then you are in good shape.

I've also been hesitant to consider V a major library on equal status with the standard C++ libraries. Again, I'm changing that idea, and beginning with V 1.21, the general philosophy will be to install V libraries, include files, and utility applications in the same directories used by X applications for X systems, and the main location of includes and libraries for MS-Windows. For most users, this will greatly simplify things. For some, it may mean an interaction with your system administrator to get V properly installed. I'd appreciate feedback on this new approach.

Directory Structure
This section describes the directory structure of the V source distribution. The V directory structure has been designed to allow you to either install V in a personal directory, or at a higher system level.

The file hierarchy is:
 * /v: The main V directory.
 * /v/appgen: V application generator program.
 * /v/bccide: MS-Windows build files for Borland C++.
 * /v/bccide/vdll: MS-Windows build files for Borland C++ version of V DLL.
 * /v/bin: The /bin directory is used to hold the binaries of V sample programs during build time. No actual binaries are included on the distribution, but several subdirectories should be created when V is unpacked.
 * /v/bccide/vdll: MS-Windows build files for Borland C++ version of V DLL. See the Readme.txt file.
 * /v/bmp2vbm: Source for a simple MS-Windows and OS/2 .bmp bitmap format to .vbm V bit map format converter.
 * /v/Configs: Various make configuration files for Linux/Unix and mingw32/cygwin versions.
 * /v/doc: The V documentation. The documentation included in the distribution is in HTML.
 * /v/draw: Source for the VDraw example program. Examples that are identical across platforms use a .cpp</tt> file extension.
 * /v/drawex: Very simple V draw example from C/C++ Users Journal article.
 * /v/examp: Source for a simple V example.
 * /v/gnuwin32: Files that may be needed to compile and use V for the cygwin and gnuwin32 Windows compilers.
 * /v/iconed: Source for V Icon editor.
 * /v/icons: Source for a large number V vbm bitmaps useful for tool bars.
 * /v/includew/v: Source for the MS-Windows  *.h </tt> V header files.
 * /v/includex/v: Source for the X  *.h </tt> V header files.
 * /v/lib: Compiled version of the V library will be placed under appropriate subdirectories here during build.
 * /v/msvc: Project and make files for Microsoft VC++ 4.
 * /v/msvc6: Project and make files for Microsoft VC++ 6.
 * /v/obj: Compiled object code is saved under here.
 * /v/objm: Compiled object code for Motif version is saved under here.
 * /v/srcwin: The full C++ source for the Ms-Windows V library. The files use a .cpp</tt> extension.
 * /v/srcx: The full C++ source for the X V library. Most files use a .cxx</tt> extension. Files with a .cpp</tt> extension are identical to their counterparts in the /srcwin</tt> directory.
 * /v/test: The test program used to test V functionality.
 * /v/texted: Source for a simple editor based on vTextEdit class.
 * /v/tutor: The source code for the tutorial example.
 * /v/vide: The source code for VIDE, the V Integrated Development Environment.
 * /v/vopengl: Source for examples for V vBaseGLCanvasPane class that interfaces to OpenGL.
 * /v/watcom: Project and make files for Watcom C++ compiler.

Microsoft Windows
Believe it or not, all the object code generated by the various compilers available for Windows is incompatible across compilers! This means it is not easy to distribute V already compiled for every compiler available. For one thing, I just can't afford to buy that many compilers.

This incompatibility means two important things. First, you must use a library for V compiled with your compiler. I've tried to supply project or make files required for the major compilers, but not all are available. The binary distribution also has precompiled versions for several major Windows compilers.

Second, when you compile your apps for V, you must be very careful about the compilation model you specify. For Windows 3.1, the best model is usually called Large. (WARNING! V has not been tested with Windows 3.1 since about version 1.16.) While WIN32 doesn't have the memory model problem, it does have calling convention and data alignment problems. You MUST be careful to compile the V library AND your own applications using the same memory model or calling conventions. These options are usually buried somewhere on an options menu. I can't provide exact information about this. It is your job to understand your compiler enough to do this.

I've selected a calling convention for the V project files I provide. You should check what they are, and be sure they match. I don't think they are always the default settings.

For example, the WIN32 version for the Borland compiler requires that word</tt> alignment be used. The compiler default is byte</tt>, so you will have to change this for your projects. The project examples supplied have generally had their options set as required. You should examine the settings, and use the same ones for your applications. You cannot mix compilers or even compiler code options.

It does seem, however, that you can build your applications with a data alignment bigger than V's. V is built with word</tt> alignment, but apparently it is ok to build your apps with 4 byte</tt> or 8 byte</tt> alignment and use it with the default 2 byte</tt> V library.

The standard distribution includes subdirectories for each compiler: Borland (/bccide</tt>), Microsoft (/msvc</tt>,/msvc6</tt>), Watcom (<tt>/watcom</tt>), and mingw32 (<tt>/gnuwin32</tt>). For the IDE based versions, you should be able to use the project files to get started. For the mingw32 distribution, please see the section below on mingw32.

General Instructions for Precompiled library
The binary distribution is found at <tt>ftp://objectcentral.com/bin-dist</tt>. The binaries are for the following compilers:

Mingw32 egcs. This was compiled using the latest mingw32 egcs distribution.

Borland C++ 5.01 - This should work with BCC 5.01 and later.

How to do it
The idea is to use the standard <tt>/bin</tt>, <tt>/include,</tt> and <tt>/lib</tt> directories used by your compiler. The V utility programs (vappgen, vide, etc.) are actually compiled with mingw32/egcs, and should execute with any compiler. The V include files, which belong on <tt>.../include/v</tt> are also common across all Windows compilers. I've archived and compressed these with tar and gzip. Executables of these two utilities are available on the ObjectCentral ftp site under <tt>dosutils</tt> if you need them.

Finally, there is a separate version of the compiled static V library for each of the above compilers.

Download <tt>v122-win-util.tgz</tt> and <tt>v122-win-inc.tgz</tt> for the common files. Download <tt>v122-win-lib-xxx.tgz</tt> with the appropriate <tt>xxx</tt> for your compiler.

Then, copy <tt>v122-win-util.tgz</tt> to the proper <tt>/bin</tt> directory. This can actually be any directory in your path, but I think the best convention is to put them on the bin directory of your compiler. Gunzip and untar the file: cd /wherever/bin gunzip -d v122-win-util.tgz tar -xvf v122-win-util.tar Copy <tt>v122-win-inc.tgz</tt> to the <tt>/include</tt> directory used by your compiler. This directory will contain standard files such as <tt>windows.h</tt> and <tt>stdlib.h</tt>. Unpacking the V include files here will produce a subdirectory (<tt>.../include/v</tt>) for the V include files. cd /whatever/include gunzip -d v122-win-inc.tgz tar -xvf v122-win-inc.tar Finally, do the same for the compiled library files. cd /whatever/lib gunzip -d v122-win-lib-xxxx.tgz tar -xvf v122-win-lib-xxxx.tar At this point, V should behave like any other library and include file used by your compiler, and will be easy to use. So far, the only special thing V requires is at LEAST word alignment. We've had pretty reliable reports that using 2-word or 4-word alignment will also work for your apps, even with word V libraries.

GNU g++ - mingw32/egcs
Now that there seems to be a really good, stable version of GNU C++ for Windows, namely the mingw32 2.8.1 distribution, and the corresponding egcs version, V will be kept in sync with that distribution.

It seems that the Ming32 version may be moribund, given the latest progress with the egcs version of gcc. V will try to follow these distributions, and keep the makefiles and other things up to date. As of V 1.21, the egcs compiler will be the main one used for GNU WIN32 versions. (V will try to keep up with the pending re-consolidation of egcs and GNU g++ as version 3.0.)

How to compile your own Applications
After you have a working version of V built (and probably installed on the mingw32/egcs directory path), either by installing the precompiled version or building your own version, it is fairly easy to use and include the V library. The main thing is to use the required <tt>-l</tt> switches to g++ to load the proper libraries. Use: g++ $(YOUROBJECTS) -lV -lcomctl32 -mwindows -or, for OpenGL apps- g++ $(YOUROBJECTS) -lV -lVgl -lcomctl32 -mwindows All the libraries needed for Windows are automatically included with the option <tt>-mwindows</tt> (you may also need to add <tt>-lcomctl32</tt>).

If you want to add icon resources, see the example vgen.rc file in the /v/appgen directory. You can replace the .ico file with whatever icon you want. You then need to add a dependency in your Makefile to compile the .rc file with windres, and include the resulting output file on the link line. The Makefile for vgen in /v/appgen includes an example of how to do this.

Instructions for rebuilding V for mingw32

 * 1) Unzip the V Windows distribution. You must be sure to use an unzipper that preserves file case, or manually rename all the files to use lower case. While Windows doesn't care, gnu make does.
 * 2) You must now create the proper version of /v/Config.mk. Usually, this is a matter of copying the proper version of Config.Mk from the /v/Configs directory. For the mingw32 version, the file to copy is /v/Configs/CfgMing.mk. Copy it to /v/Config.mk. The default version assumes that you have unpacked the V distribution to c:/v, and that you have installed mingw32 on C:/mingw32. You can change this by editing the copied version of /v/Config.mk.
 * 3) The Makefile in the /V root directory is intended for use on Unix/Linux machines. It does NOT work for Windows. However, the Makefiles on the directories with the V library and other V applications do work on Windows, and are used for both the X version on Linux/Unix, and for the MS-Windows GNU WIN32 versions. Currently (June 1999), all versions of GNU WIN32 may not include the all headers needed to correctly compile V.First, TRY to compile V, then if the headers are missing, copy them to your GNU WIN32 compiler's include directory.You MAY need to copy C:/v/gnuwin32/include/commctrl.h to C:/mingw32/include/commctrl.h (or wherever the mingw32 /include directory is on your system.) You need this file to compile V 1.18 and later for the Common Control dll. You will also add -lcomctl32 to your link lines in your makefile. (For some reason, the mingw32 distribution includes comctl32.a, but fails to include the corresponding header file -- that item is still being resolved. For now, V will provide the header.)Also, if you choose to compile for OpenGL, you may need to copy the entire gl subdirectory (found at v/gnuwin32/include) to the GNU WIN32 include directory (as a /include/gl subdirectory).
 * 4) cd to each of these directories and run `make' for each of the following. (The top level Makefile in C:/v has X specific stuff and doesn't work. Also, since make is case sensitive, you might have to use `make -f makefile'.)
 * srcwin (required)
 * appgen (useful - see documentation)
 * iconed (useful - especially for icons)
 * icons (shows predefined V icons you can use)
 * draw (example only)
 * drawex (example only)
 * examp (example only)
 * texted (example only)
 * tutor (example only)
 * vide (very useful IDE for mingw32!)
 * 1) Putting the V headers in the mingw32 directory path has the advantage of eliminating the need for extra include directives in your makefiles. (An older version of V found at the mingw32 site should be replaced with this latest version.) After you build V, you will find it easiest to copy libV.a from v/lib/gnuwin32 to mingw32/lib/libV.a, as well as all the V headers in from v/includew/v to mingw32/include/v. This will allow you to easily update versions of V, and to compile your own applications with V.To do this, after you've built the V library, change to the home /v directory, and enter:
 * <tt>make installgnuwin32</tt> This will copy all the required header, library, and binary files to the mingw32 directories as defined in Config.mk.
 * 1) If you want to build OpenGL applications with mingw32, the header files are located at gnuwin32/include.

Instructions for rebuilding V for Cygwin B20
One of the main features of the Cygwin support for the V library is the fact that it may be built for both X and Windows GUI targets.

NOTE: To use the X version you will have to download precompiled library and header files of X11R6.4 from Cygwin32 Porting Project's homepage at http://www-public.rz.uni-duesseldorf.de/~tolj, which is also the official supporter and a X windows server for your Win32 machine, i.e. X-Win32 from http://www.starnet.com.

<tt>
 * TO REBUILD THE V LIBRARY (X and WINDOWS) FOR CYGWIN32
 * 1) To extract the compressed v-1.22.tar.gz archive you will have to do the following within your bash shell:
 * gunzip v-1.22.tar.gz

</tt> Now you will have the V distribution within the subdirectory v/.
 * tar xf v-1.22.tar
 * 1) You will have to build either the X or the Windows version of V for Cygwin. You can build both, but you will have to build each separately, and copy the include and lib files after each build. Note that the X version uses the v/includex/v include files, while the MS-Windows version uses /v/includew/v files. It is not particularly easy to use both the X and Windows V libraries at the same time.
 * 2) Making the X version: Copy /v/Configs/CfgCygX.mk to /v/Config.mk, and edit it as follows:
 * - set HOMEV to the home directory of your V distribution
 * - set X11RV = X11R6.4 (if using our recommended X11 libraries)
 * - Now you may type "make" and build the library and some example applications.
 * 1) Making the Windows GUI version: Copy /v/Configs/CfgCygW.mk to /v/Config.mk and edit that file as follows
 * - set HOMEV to the home directory of your V distribution
 * 1) cd to each of these directories and run "make" for each of the following. (Don't use the top level Makefile in /v since this is used to build the X version).
 * srcwin (required)
 * appgen (useful - see documentation)
 * iconed (useful - especially for icons)
 * icons (shows predefined V icons you can use)
 * test (tests V lib - not usually needed)
 * bmp2vbm (not needed, functionality now included in iconed)
 * draw (example only)
 * drawex (example only)
 * examp (example only)
 * texted (example only)
 * tutor (example only)
 * vide (very useful IDE for cygwin32!)
 * 1) If you want to build OpenGL applications with cygwin32, the header files are located at gnuwin32/include.

Now that you have a working version of V built (and probably installed on the cygwin\bin directory path), it is fairly easy to use and include the V library. The main thing is to include the required -l switches to g++ to load the proper libraries. Use: g++ $(YOUROBJECTS) -s -e _mainCRTStartup -lV -lcomctl32 -mwindows
 * TO COMPILE YOUR OWN APPLICATIONS

A similar model line for using the X version of the V library is: g++ $(YOUROBJECTS) -s -e _mainCRTStartup -L/usr/X11R6.4/lib -lV -lXaw -lXmu -lXt -lXext -lX11 -lICE -lSM All the libraries needed for Windows are automatically included with the option -mwindows (you may need to add -lcomctl32).

If you want to avoid using the Cygwin DLL, you can also add the -no-cygwin switch, and link to the mingw32 libraries. See the Cygwin documentation for more info. Also check out Mumit Kahn's info.

If you want to add icon resources, see the example vgen.rc file in the /v/appgen directory. You can replace the .ico file with whatever icon you want. You then need to add a dependency in your Makefile to compile the .rc file with windres, and include the resulting output file on the link line. The Makefile for vgen in /v/appgen includes an example of how to do this.

Please read the file /v/Configs/cygnus-readme.txt for the latest info on compiling V with Cygwin.

Borland
Windows specific files for Borland 5.0 are kept on BCCIDE. That directory includes .IDE files for Borland C++, .RC, .DEF, and .ICO files. The project files assume that BCC is on drive C:. If you have BCC 4.5, or keep BCC on a drive other than C:, then you will have modify the project files to change the include file search paths. Note that the BCC 5.0 project files only work for WIN32. V will no longer be supported for 16 bit compilers.

The subdirectory <tt>/v/bccide/vdll</tt> contains Borland makefiles for building a DLL version with Borland C++. It is VERY easy. See the Readme.txt file. You use the provided makefiles using a DOS window. Simply change to this directory, and run Borland's make on the Makefile in this directory. When you are done, you will have V122BCC.DLL (the DLL), and V122BCC.LIB (the load library).

Now you can build V applications using Borland C++, and link to the V122BCC.LIB, and include the V122BCC.DLL in the same directory as your executable.

Microsoft Visual C++
This distribution now includes make/project files for Microsoft VC++. There are two versions: for MSVC 4.0, which were built using the cheap Standard Edition, and can be used with MSVC 5.0 as well; and MSVC 6.0.

Beginning with VC++ 6.0, Microsoft has done things to their C++ compiler that makes it really have trouble with the existing V code. The main obnoxious thing they've done is revert to old style handling of loop variables. I've had to change a bunch of code to allow default settings to be used.

The following are some of the things required to get V to compile with MSVC++ 6.0 (These notes are based on using the Standard Edition. They could be different for the Professional versions. I don't claim to be an MSVC++ expert, and any better usage notes would be appreciated.)


 * The example workspace files assume V is found at <tt>C:\V</tt>. The following notes assume the same. Change references to <tt>C:\V</tt> to wherever you've installed V.
 * You will generally create a new, blank workspace for your projects.
 * To enable the compiler to find V header files, add <tt>C:\v\includew</tt> under Additional include directories under the C/C++ tab of the Project Settings dialog.
 * One way for the linker to find the V library is to add <tt>vlib.lib</tt> as the first file in the Object/library modules item of the Link tab of the settings dialog. You then need to add <tt>C:\v\msvc6\vlib\release</tt> (or wherever you've built the V library) to the Additional library path item. You can specify separate paths for debug and release versions of the V library if you need to, or simply use the release version for the "All Configurations" settings. There might be easier ways to specify how to use the V library, but this way worked for me.
 * Important: You must add <tt>comctl32.lib</tt> to the Object/library modules list in the Link tab of the settings dialog. You can add this to the "All Configurations" settings if you wish.
 * If when you try to build the <tt>.exe</tt> of your project you get messages about incompatible library uses, add the names of the libraries listed to the Ignore libraries: item of the Link tab of the Project Settings dialog.

Watcom
Watcom project files are found in the WATCOM directory. There are various subdirectories with different WIN32 and Win3.1 project files. There is a subdirectory called WATCOM11 that has some contributed makefiles that are known to work with Watcom 11.

Other Compilers
If you want to compile V with a different compiler, it isn't too hard. To build the library, you include ALL the files in the <tt>v/srcwin</tt> directory. Specify <tt>v/includew</tt> in the include search path. V has been designed to work only with the LARGE model for Win3.1. It works with whatever calling convention you need for WIN32.

The djcpp version has difficulty compiling V. It was never intended to compile Win32 apps, and so V will not easily compile with djcpp.

X Windows
Building V for various X Windows flavours of Unix system uses the standard gnu version of the Unix <tt>make</tt> tool. (Note: you must use a <tt>make</tt> compatible with the gnu version of <tt>make</tt>. The V makefiles use features and conventions supported by the gnu version. Some native <tt>makes</tt> do not support all the features, and will generate error messages.) The main <tt>/v</tt> directory contains a <tt>Makefile</tt> and a file called <tt>Config.mk</tt>. The directory <tt>/v/Configs</tt> contains several versions of <tt>Config.mk</tt> that usually must be customized to build V for your system. The <tt>Makefile</tt> and the <tt>Config.mk</tt> files contain more information about building V.

Beginning with V Version 1.22, the main widget set supported for X is Motif/LessTif. Until 1.22, the Athena widget set had been the main one. However, as of version 0.88, LessTif seems to be stable enough to fully support V. Since this widget set looks much better than Athena, and since many Linux distributions are replacing the standard Athena with Athena3D (which breaks the look of V Athena), the LessTif version will now be the main version of V. V will continue to run under Athena, but it is likely that not all new features will be supported under Athena (e.g., multiple-list selection when that is added). Please see the section [#Motif Motif vs. Athena] below.

Instructions for building V for Linux

 * 1) Gunzip and tar the V distribution to a directory of your choice. The files will extract to a <tt>/v</tt> subdirectory.
 * 2) You must now create the proper version of /v/Config.mk. Usually, this is a matter of copying the proper version of Config.mk from the /v/Configs directory. This will be ConfigX.mk for the X Athena version, or ConfigM.mk for the LessTif/Motif version. (Use ConfigM.mk if you have LessTif 0.88 or later, or if you have Motif.) The default version assumes that you have unpacked the V distribution to <tt>$(HOME)/v</tt>, where <tt>HOME</tt> is the standard environment variable. You can change this by editing the copied version of /v/Config.mk.
 * 3) From the main <tt>/v</tt> directory, run `make'. This should build the static version V library and all the V utility applications. (You can build a shared library version -- see the comments in the Makefile.) The following utilities are built:
 * appgen (useful - see documentation)


 * iconed (useful - especially for icons)


 * icons (shows predefined V icons you can use)


 * draw (example only)


 * drawex (example only)


 * examp (example only)
 * texted (example only)
 * tutor (example only)
 * vide (very useful IDE)
 * 1) By default, the V makefile will try to compile the OpenGL library. If you don't have OpenGL or Mesa installed on your system, the makefile will generate a bunch of errors about missing OpenGL include files, and you can safely ignore them.
 * 2) After you build V, you will find it easiest to install the library and include files to standard places. To do this, first <tt>su</tt> or logon as <tt>root</tt>. Then enter <tt>make installLinux</tt>. This will install V to the standard X11 directories.

How to compile your own Applications
After you have a working version of V built (and probably installed), either by installing the precompiled version or building your own version, it is fairly easy to use and include the V library. The V application generator, <tt>vgen</tt>, will build a makefile with the proper includes and library switches. You can also use the provided sample makefiles as starting points.

You can also build your own makefiles. The main thing is to use the required <tt>-l, -L, and -I</tt> switches to g++ to load the proper libraries and include files. To compile, use: g++ $(YOURSRC) -I/usr/X11R6/include To link, use for LessTif/Motif: g++ $(YOUROBJECTS) -L/usr/X11R6/lib -lV -lXm -lXmu -lXt -lXext -lX11 or for Athena g++ $(YOUROBJECTS) -L/usr/X11R6/lib -lV -lXaw -lXmu -lXt -lXext -lX11 For OpenGL applications, add <tt>-lVgl -lGLw -lGLU -lGL</tt> to the library switches.

Other Unix Flavors
A series of <tt>Makefiles</tt> is included with the V distribution to build the library on various Unix systems. In the main <tt>/v</tt> directory is a file called <tt>Config.mk</tt> which usually needs to be customized before building. The prototype <tt>Config.mk</tt> files are contained in the subdirectory <tt>/v/Configs</tt>. There are two versions of <tt>Config.mk</tt> supplied: <tt>ConfigX.mk</tt> for the Athena widget based version, and <tt>ConfigM.mk</tt> for the Motif widget based version. Before you compile, you should copy the appropriate file to <tt>/v/Config.mk</tt>, edit it to customize it for your system, then type <tt>make</tt> from the <tt>/v</tt> directory. This will build the V library and all the utility programs.

The <tt>Config.mk</tt> file, and the various <tt>Makefiles</tt> contain lots of comments about building V on your platform. Please read those files directly for more critical information about getting V working on your system.

gtk
The gtk version of V is still a separate distribution. Please see the instructions included with it. It will eventually become the mainline V Linux distribution.

Motif vs. Athena
Beginning with V 1.22, LessTif will become the standard widget set supported by V. You must have at least LessTif version 0.88 to work with V, however. You also may be able to use a standard Motif library, but I've gotten mixed reports that V doesn't work correctly with real Motif libs.

I know I said I would provide minimal LessTif/Motif support in the V 1.21 release, but I've chanaged my mind. First, LessTif 0.88 looks pretty stable. I've finally been able to chase down all but a couple of problems (visual, not functional) with LessTif. Programs built using this version look much better, and work better with the current X Window Managers (KDE specifically). And some late versions of Linux (Caldera, for example) provide the 3D Athena library by default, which ruins the look of V/Athena.

OS/2
Directions for compiling on OS/2 are included in the OS/2 distribution. Since the OS/2 version was just released, there are not as many prebuilt project or makefiles available. The mingw32 files should serve as a good basis for the EMX compiler. As users contribute feedback, this situation should change.

OpenGL
V will only work with OpenGL if you have it installed on your system. Beginning with V 1.21, OpenGL support has been split into a separate library file. This may cause some compilation errors from V makefiles if you don't have OpenGL, but you can ingore them.

OpenGL on Microsoft Windows
Windows comes standard with the OpenGL DLL. You must have the appropriate import library to use the DLL, which usually comes with the various compilers. The only problem seems to be with the gnu mingw32/cygwin compiler. The required include files are available under the <tt>/v/gnuwin32</tt> directory if you need them.

OpenGL on X Windows
V seems to work flawlessly with Mesa on Linux, and with standard OpenGL on most other systems. Note that you must have the Motif or Athena OpenGL widget library (libGLw) built and available. If you don't have OpenGL or Mesa, you won't need libVgl.a.

This user guide, installation, and reference manual, The V C++ GUI Framework User Guide and Reference Manual, Version 1.22, may be reproduced and distributed, in whole or in part, subject to the following conditions: My goal is to get as many people as can be helped using V. If the terms of this documentation copyright are unsatisfactory, please contact me and we can probably work something out.
 * 1) The copyright notice above and this permission notice must be preserved complete on all complete or partial copies.
 * 2) You may not translate or create a derivative of this work without the author's written permission.
 * 3) If you distribute this manual in part, you must provide instructions and a means for obtaining a complete version.
 * 4) You may make a profit on copies of this work only if it is included as part of an electronic distribution of other free software works (e.g., Linux or GNU).
 * 5) Small portions may be reproduced as illustrations for reviews or quotations in other works without this permission notice if proper citation is given.