\documentclass[letterpaper]{article}

% Try to fill up the page!
% This was from another example - we will ignore it for now

\normalsize
\setlength{\topmargin}{0in}
\setlength{\oddsidemargin}{1in}
\setlength{\evensidemargin}{.05in}
\setlength{\marginparwidth}{0in}
\addtolength{\textheight}{1in}
\addtolength{\textwidth}{.7in}
% \code is a piece of code
%\newcommand{\code}{\texttt}
\def\code#1{\texttt{#1}}
% \V\ is V
\newcommand{\V}{\emph{\textbf{V}}}
\newcommand{\rta}{->}
% special math chars I need: -> ~ ^
\newcommand{\tild}{\~{ }}

% \Class is used to start a new class description at page begin
%----old \newcommand{\Class}[1]{\newpage \markboth{#1}{#1} \section* {#1}}
\newcommand{\Class}[1]{\section {#1}}
%\Indextt for tt index
\newcommand{\Indextt}[1]{\index{#1@\texttt{#1}}}
% \Meth is for a method
\newcommand{\Meth}[1]{\subsubsection* {#1}}
% \Cmd is for a dialog command
\newcommand{\Cmd}[1]{\subsubsection* {#1}}
% \Param is a parameter description
\newcommand{\Param}[1]{\subparagraph {#1}}
% kill off the figfont
\newcommand{\SetFigFont}[3]{}%
% \Sect is used to set typeface of chapter and section titles
\newcommand{\Sect}[1]{\emph{#1}}

% Method environment that allows parameters to be entered with
% the \Param command between the \begin and \end.
\newenvironment{Method}[1]{\Meth{#1}
\begin{description}
\begin{description}}
{\end{description}
\end{description}}

% An environment for a definition
\newenvironment{Def}[1]{\begin{description} \item[#1]}{\end{description}}

\newenvironment{Point}{\begin{itemize} \item }{\end{itemize}}


% Macros for html
%
% First, the LatexVersion

\def\texhtm#1#2{#1}
\def\href#1#2{}
\def\htm#1{}

%%tth:\def\texhtm#1#2{#2}
%%tth:\def\href#1#2{\special{html:<a href="#1">}{#2}\special{html:</a>}}
%%tth:\def\htm#1{\special{html:#1}}

\usepackage{graphics}


%==========================================================================
\begin{document}
\href{http://www.objectcentral.com}{[Object Central Home]}

\begin{center}
\textbf{Installation Instructions for V}

\input{vvers.tex}

Copyright \copyright 1998, Bruce E. Wampler
\end{center}


\htm{<HR>}

\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. Not all systems are covered here, but there should
be enough information to get you through the process.

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.

I do hope to be able to provide DLL versions for MS-Windows and
shared libraries for Linux systems in the near future.

\section{Obtaining V}

The main sources of the \V\ library is found at the Object Central
Internet site, \emph{www.objectcentral.com}. You can obtain the
files either from html links on the Object Central web page, or
you can download them directly from the Object Central ftp site,
\emph{objectcentral.com}, via anonymous ftp.

The files of interest:

\begin{description}

\item [v-1.18.tar.gz]  Gzipped tar file of the Full \V\ version for X and MS-Windows.
This includes all source code for X and MS-Windows, and source
form of documentation for all versions. (PostScript and HTML
files are included in separate archives.)

\item [vwin118.zip] DOS ZIP format archive of Windows version. This
distribution includes code for Windows 3.1 and Win32 (suitable
for NT and Windows 95). It does not include the documentation.

\item [vos2-117.zip] DOS ZIP format archive of OS/2 version. This
distribution includes a standalone distribution for OS/2. Since
it is being developed separately, it will not always by in
sync with the X and MS-Windows versions.

\item [vref118.ps.gz] Gzipped PostScript file of V Reference Manual.

\item [vref118.html.tar.gz] Gzipped tar format of the HTML version of
\V\ reference manual. This is suitable for loading to a Windows
platform and viewing with a browser such as Netscape. 

\end{description}

If you are downloading to a MS-Windows system, you might need to
change the file names to something more compatible with Windows.

\section{Unpacking V}

The \V\ distribution files are either in ZIP format, a common format
used on MS-Windows, Gzip format (GNU ZIP), or Gzipped tar format.
Tar is a archive utility with Unix origins.

If you already have a version of ZIP, gzip, or tar, you are all
set. If you run on a Unix platform, you will have gzip and tar.
Free versions of gzip and tar are available at the Object Central
ftp site under the \emph{dosutils} directory. Download those utilities,
and then unpack and unarchive the \V\ files. After copying the
distribution files to the parent directory of where you want to
install \V, (the files are unpacked to a \code{/v} directory), 
use the following procedure (replace with the correct file name):

\begin{verbatim}
    gunzip vref-118.html.tar.gz
    tar xvf vref-118.html.tar
\end{verbatim}

You will then be ready to compile the distribution.

\section{Organization of the V 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.
This will let you define appropriate search paths for the \V
header files to your compiler - e.g., your IDE or Makefile.

The file hierarchy is:

\begin{description}
\item[/v] The main \V\ directory.

\item[/v/appgen] V application generator program.

\item[/v/bccide] MS-Windows build files for Borland C++.

\item[/bmp2vbm] Source for a simple MS-Windows and OS/2 \code{.bmp} bitmap
format to \code{.vbm} V bit map format converter.

\item[/v/bin] The \code{/bin} directory is used to hold the binaries
of \V\ sample programs. No binaries are included on the distribution,
but most appropriate subdirectories for various architectures and
platforms should be created by the unpacking process.

\item[/v/doc] The sources for \V\ documentation. The documentation
is in \LaTeX format. The standard distribution includes only the source
\LaTeX files. Other versions, including HTML and Postscript, are
available from the \V\ ftp site.

\item[/v/draw] Source for the VDraw example program. Examples that
are identical across platforms use a \code{.cpp} file extension.

\item[/v/drawex] Very simple V draw example from C/C++ Users Journal
article.

\item[/v/examp] Source for a simple \V\ example.

\item[/v/includex/v] Source for the X \code{*.h} \V\ header files.

\item[/v/includew/v] Source for the MS-Windows \code{*.h} \V\ header files.

\item[/v/include2/v] Source for the X \code{*.h} \V\ header files.
(Only included in OS/2 distribution.)

\item[/v/lib] Compiled version of the \V\ library will be placed
under appropriate subdirectories here. No precompiled libraries are
included in the standard distribution.

\item[/v/mingw32] Files needed for mingw32 compiler.

\item[/v/msvc] Project and make files for Microsoft VC++.

\item[/v/obj] Compile object code is saved under here.

\item[/v/srcx] The full C++ source for the X \V\ library. The files
use a \code{.cxx} extension.

\item[/v/srcwin] The full C++ source for the Ms-Windows \V\ library. The files
use a \code{.cpp} extension.

\item[/v/src2] The full C++ source for the OS/2 \V\ library. The files
use a \code{.cpp} extension.

\item[/v/test] The test program used to test \V\ functionality.

\item[/v/texted] Source for a simple editor based on vTextEdit class.

\item[/v/tutor] The source code for the tutorial example.

\item[/v/vxgl] Source for V canvas class that interfaces to X
version of OpenGL.

\item[/v/watcom] Project and make files for Watcom C++ compiler.

\end{description}

\section{Compiling: MS-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 practical to
distribute V already compiled for every compiler avaiable.
For one thing, I just can't afford to buy that many compilers.

This incompatibility means two \emph{important} things.

First, you must compile V with your compiler. I've tried to supply
project or make files required for the major compilers, but
not all are available.

You must be very careful about the compilation model you
specify. For Windows 3.1, the best model is usually called
Large. 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 \code{word} alignment be used. The default is \code{byte}.
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.

The standard distribution includes subdirectories for each compiler:
Borland (\code{/bccide}), Microsoft (\code{/msvc}), Watcom
(\code{watcom}), and mingw32 (\code{mingw32}). For the IDE based
versions, you should be able to use the project files to get started.
For the mingw32 distribution, please read the \code{rdmw32.txt} file
in the \code{/mingw32} directory.

\subsection{mingw32}

The mingw32 compiler is becoming the "official" \V\ compiler. Since
it is free, the \V\ distribution will be kept in sync with the
latest mingw32 version. It is currently compiled in a DOS window.
You may find it easier to place the \V\ header files directly
under mingw32: e.g., \code{/mingw32/include/v}. Building \V
with mingw32 is more like building under Unix. It uses a
special version of the \code{Config.mk} file and the same
\code{Makefiles} for the example applications. The only tricky
thing about mingw32 at the moment is that the files must be
extracted in such a way as to preserve filename case. Using
gzip and tar to extract the full \code{v-1.18.tar.gz} file
is probably best.

\subsection{Borland C++}

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. I couldn't get BCC 5.02 to compile the 16 bit version.
There is a project file for BCC 4.5 that builds a 16 bit version.

\subsection{Watcom}

Watcom project files are found in the WATCOM directory.
There are various subdirectories with different WIN32 and
Win3.1 project files.

\subsection{MS Visual C++}

This distribution now includes make/project files for Microsoft
VC++. There are 16 bit versions for MSVC 1.52, and for
MSVC 4.0, which were built using the cheap Standard Edition.
They should be compatible with the expensive later version.

\subsection{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 \code{v/srcwin} directory. Specify  \code{v/includew} 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 seems to have difficulty compiling \V.

\section{Compiling: Unix, Linux}

A series of \code{Makefiles} is included with the \V\ distribution
to build the library on various Unix systems. In the main
\code{/v} directory is a file called \code{Config.mk} which
usually needs to be customized before building. Actually, there
are two versions of \code{Config.mk} supplied: \code{ConfigX.mk}
for the Athena widget based version, and \code{ConfigM.mk}
for the Motif widget based version. Before you compile, you
should copy the appropriate file to \code{Config.mk}, edit
\code{Config.mk} for your system, then type \code{make}
from the \code{/v} directory.

The \code{Config.mk} file, and the various \code{Makefiles}
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.


\section{Compiling: 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.

\htm{<HR>}

\href{http://www.objectcentral.com}{[Object Central Home]}


\end{document}
