Building VisIt from source on Windows
======================================
======================================

Required packages
==================

VisIt requires several libraries in order to build successfully. The table below lists the library packages that VisIt requires. Pre-built versions of the libraries listed below are provided in the VisIt development distribution to make VisIt easier to build. The only library that is not provided as a pre-built binary is Qt. You can either download Qt free edition for Windows or you can purchase a Qt development license. In either case, you must build Qt yourself. We use Qt 3.0.2 to develop VisIt on Windows, though we use versions ranging from 2.3.0 through 3.3.0 on other platforms.

Package   Version      Download location
VisIt     1.4.1        ftp://ftp.llnl.gov/pub/visit/visit1.4.1/VisItDev1.4.1.exe
VTK       4.2+         ftp://ftp.llnl.gov/pub/visit/3rd_party/Vtk_cvs_2003_10_28.tar.gz                        http://www.kitware.com
CMake     1.8+         http://www.cmake.org/CMSetup182.exe
Python    2.1.2 2.3.4  ftp://ftp.llnl.gov/pub/visit/3rd_party/Python-2.1.2.tar.gz
                       http://www.python.org
Mesa3D    5.0+         ftp://ftp.llnl.gov/pub/visit/3rd_party/Mesa-5.0-mangled.tar.gz
                       http://www.mesa3d.org
Qt        3.0.2+       http://www.trolltech.com


Required Compiler
==================

The VisIt source distribution for Windows comes with project files for Microsoft Visual C++ 6.0 and Microsoft Visual C++ .NET 2003. The project files for the version 6.0 compiler are in the projects directory and the .NET 2003 compilers project files are in the projects-MSVC7.Net directory. VisIt may compile with other vendor compilers but we only support compiling VisIt with the afore-mentioned compilers.

Project file issues
====================

It has been reported that the VisIt project files for the version 6.0 compiler reference qt-mt302.lib, which is the 3.0.2 version of Qt. Some future version of the VisIt source distribution for Windows will prompt you for your Qt include directory and library name and then use those values in the project files. Until then, however, it will be necessary for you to edit the project files and replace qt-mt302.lib with your own Qt DLL import library. We recommend using a script to update all of the scripts at once.

The project files for the .NET 2003 compiler also reference qt-mt302.lib but the include and library directories use the %QTDIR% environment variable. Future versions of the VisIt source code distribution for Windows will prompt you for your Qt librarys location and version so the project files can be automatically updated as part of the installation process.

Installing packages
====================

First download Qt from Trolltechs Web site and then extract it to your C:\ drive. If you want to build all of VisIts other libraries from source, download those libraries as well. After downloading all of the required packages, extract them to your C:\ drive or run their installation programs. After running the package installation programs, you should have the following directories on your hard drive:

C:\VisItDev1.4.1 where version is the version of VisIt
C:\Qt

You will also have these directories if you installed VTK, Mesa, and Python instead of opting to use VisIts pre-built versions.

C:\VTK
C:\Mesa-5.0.1
C:\Python-2.1.2 or C:\Python-2.3.4

Tips before you build
======================

Much of VisIt is implemented in the form of dynamically linked libraries (DLLs) so it is imperative that all libraries are built with the Multithreaded DLL memory model. Also be sure to use the same Debug/Release setting when you build libraries. If you build any of VisIts DLLs with a different memory model, VisIt will likely crash at runtime in unexpected ways. That being said, all of VisIts support libraries must be built as DLLs. You can set the memory model in the Project settings window in the C++ code generation options.

Some scripts that run as part of the VisIt build need to have the VISITDEVDIR environment variable set. When VisIts windows development distribution is installed, this environment variable is set to the directory where the development distribution was installed. If for some reason, the environment variable was not set, please add it to the environment. To add an environment variable on Windows 2000, open the Environment variables window by opening System from the Control Panel and then clicking the Environment variables button on the advanced tab. Once the Environment variables window is open, click the New button in the User variables pane and add VISITDEVDIR with the path to the VisIt source distribution. If you installed the source distribution in the default location, you would set VISITDEVDIR to C:\VisItDev1.4.1.
Directories for include files and libraries

If you use the .NET 2003 version of the C++ compiler, you can skip this section because the provided project files have the necessary include and library directories built in so there is no need to edit your global settings.

The VisIt project files provided for the version 6.0 compiler do not currently include the directories for VisIts include files. The compiler and linker must know where to find VisIts header files and libraries and the header files and libraries of the support libraries that it uses so you will need to set global include and library directories in order to build VisIt. Open the Options window by selecting Tools->Options Once the Options window is open, choose the Directories tab and add the following include directories if you plan to build VisIt using the pre-built support libraries:

C:\VisItDev1.4.1\include\visit\
C:\VisItDev1.4.1\include\vtk\
C:\VisItDev1.4.1\include\Python\
C:\VisItDev1.4.1\include\mesa\
C:\VisItDev1.4.1\include\silo\
C:\VisItDev1.4.1\include\zlib\
C:\VisItDev1.4.1\include\tools\

If youve built any of the support libraries yourself, substitute the path to that library instead of using the included header files. You must also add the include path to Qt if it is not already in the list or VisIt will fail to build.

In addition to adding include file directories, you also must add library directories. Make sure that you add either:

C:\VisItDev1.4.1\lib\Release

or

C:\VisItDev1.4.1\lib\Debug

Building Qt
============

Download Qt and follow its build instructions. Be sure that you use the Multithreaded DLL memory model when you build it.

Building Mesa
==============

Most developers can skip this step since a pre-built version of Mesa is included in the VisIt source distribution. If you do build Mesa, be sure to build the MesaGL and OSMesa libraries as DLLs using the Multithreaded DLL memory model. Also be sure to build them both using the mangled mesa namespace.

Building VTK
=============

VisIts Windows development distribution includes pre-built versions of VTK, the visualization toolkit that VisIt uses for data manipulation and rendering, so you do not need to build it unless you want to use a newer version of VTK. Be aware that when you use a newer version of VTK, VisIt might not build because the VTK programming interface often changes drastically from release to release. 

If you want to build your own version of VTK, you must have CMake, which is a cross-platform make utility that VTK uses to generate project files for Visual Studio. Once you have CMake installed, run it a window will appear on the screen. Near the top of the window, there are options to tell CMake where to find the source code and where to build the binaries. Make sure you tell CMake that the source code is located in C:\VTK and that you want to build binaries in C:\VTK\bin.

CMake can generate project files to build VTK using the version 6.0 compiler or the .NET 2003 compiler. Choose the compiler that you plan to use for building VisIt so VisIt is built with the same compiler as was used to build VTK. If you use the .NET 2003 compiler, you might want to enable the SSE instruction set so floating point operations can be done using faster, more specialized hardware.

After telling CMake where to find source code and where to put binaries, click the Configure button to start configuring CMake to generate VTKs project files. Once CMake has been configured, a list of properties will appear in the center of CMakes window. These properties tell CMake how you want to configure VTK.

    Change the LIBRARY_OUTPUT_PATH and EXECUTABLE_OUTPUT_PATH properties to C:\VTK\bin.

    Change the BUILD_SHARED_LIBS property to ON.

    Change the VTK_USE_HYBRID property to ON.
     

Click the Configure button again so CMake creates updated Visual Studio project files for VTK. Properties that are shown in red need more information to complete. Provide the required information and click the Configure button again until all properties are gray and CMake creates the project files to build VTK.

Before you start building VTK, you need to copy VisIts implementation of vtkCamera over the native VTK implementation to work around deficiencies in VTKs camera class. Copy C:\VisItDev1.4.1\visitsrc\visit_vtk\vtkCamera.h to C:\VTK\Rendering and also copy C:\VisItDev1.4.1\visitsrc\visit_vtk\vtkCamera.C to C:\VTK\Rendering\vtkCamera.cxx.

Now that VTK has been configured, run Visual Studio and open up the VTK workspace stored in C:\VTK\bin\VTK.dsw. The .NET 2003 version of the VTK solution will have an .sln extension so open that instead if you plan to use the .NET 2003 compiler. Select the ALLBUILD project if it is not already the active project. Then set the active build configuration to ALL BUILD  Win32 Release if you want a release version of the code or use ALL BUILD  Win32 Debug if you want debugging information.

The project settings for each VTK library should already be targeted to generate code that uses a Multithreaded DLL runtime library but it makes sense to double-check and perhaps change the target processor to Pentium Pro instead of using the default blend target.

As libraries are created, they are put into C:\VTK\bin\Release if youre building a Release version or they are put into C:\VTK\bin\Debug if youre building a Debug version of the VTK library. Once VTK is done building, copy all of the import libraries and dynamic link libraries into the correct location depending on the compiler that you used to build VTK. If you built a Debug version of VTK, substitute Debug for Release in the following instructions:

Version 6.0 compiler
    Copy (*.lib) and from C:\VTK\bin\Release into C:\VisItDev1.4.1\lib\Release
    Copy all of the DLLs (*.dll) from C:\VTK\bin\Release into C:\VisItDev1.4.1\bin\Release. 

.NET 2003 compiler
    Copy (*.lib) and from C:\VTK\bin\Release into C:\VisItDev1.4.1\lib\MSVC7.Net\Release
    Copy all of the DLLs (*.dll) from C:\VTK\bin\Release into C:\VisItDev1.4.1\bin\MSVC7.Net\Release. 

Building Python
================

Use the version of Python that comes with the VisIt source code distribution for Windows. It is not difficult to build Python but there are a lot of files that need to be installed properly in a full Python release. Without the requisite files, VisIts command line interface will not have all of its available features.

Building VisIt
===============

Five project workspaces are required to build VisIt. Depending on the compiler that you plan to use, the project files are stored under the C:\VisItDev1.4.1\projects directory or the C:\VisItDev1.4.1\projects-MSVC7.Net directory. Each project directory contains five subdirectories that contain the workspaces required to build VisIt. The tables below list the names of the project workspaces and the purposes for each workspace. The workspaces appear in the table in the order in which they must be built.

Version 6.0 project workspace    Purpose
========================================
VisIt.dsw            Builds all of VisIts core libraries
PlotPlugins.dsw      Builds all of VisIts standard plot plug-ins
OperatorPlugins.dsw  Builds all of VisIts standard operator plug-ins
DatabasePlugins.dsw  Builds all of VisIts standard database plug-ins
Tools.dsw            Builds all of VisIts support tools

.Net 2003 solution   Purpose
=============================
VisIt.sln            Builds all of VisIts core libraries
PlotPlugins.sln      Builds all of VisIts standard plot plug-ins
OperatorPlugins.sln  Builds all of VisIts standard operator plug-ins
DatabasePlugins.sln  Builds all of VisIts standard database plug-ins
Tools.sln            Builds all of VisIts support tools

To build VisIt, open a project workspace, set the active configuration, which tells the compiler to build either Debug or Release code, and build the source code. Make sure that the _TOP_LEVEL project is the active project to ensure that all projects in the workspace are built. Note that you must use the same active configuration for all VisIt project workspaces or youll get unexpected runtime errors.

