
         Instructions for Building and Installing Vidalia from Source


Before building and running Vidalia, you will need to have the following
packages installed:

  * Qt >= 4.3           http://qt.nokia.com/downloads
  * Tor >= 0.2.0.34     https://www.torproject.org/download.html
  * CMake >= 2.4.0      http://www.cmake.org/HTML/Download.html


Linux/BSD/Unix
--------------
  1. To configure and compile Vidalia, you can run the following sequence of
     commands:

       mkdir build && cd build
       cmake ..
       make

  2. When the previous command finishes, Vidalia's binary will be
     placed in the build/src/vidalia/ directory.
  
  3. Optionally, you can run `make install` to install Vidalia into
     your /usr/local/bin/ directory. 


Mac OS X
--------
CMake on Mac OS X gives you the option of compiling Vidalia from the command
line using standard Unix Makefiles, or generating an Xcode project if you
prefer building from an IDE.

  1. To build Vidalia from the command line, you can run:

        mkdir build && cd build
        cmake ..
        make

     Alternatively, you can have CMake generate an Xcode project for Vidalia
     by running:

        mkdir xcode && cd xcode
        cmake -G Xcode ..

  2. If you built from the command line, Vidalia's binary will be in an
     application bundle located at build/src/vidalia/Vidalia.app. You can copy
     Vidalia.app to your Applications folder, if you prefer.

     If you're building from a CMake-generated Xcode project, you can simply
     click "Build & Go" in Xcode to build and run Vidalia. Or, you can run
     'xcodebuild' if you prefer building from the command line.


Windows with MinGW
-------------------
  1. Make sure the following directories are in your PATH environment
  variable:
      
        * CMake (e.g., "C:\Program Files\CMake 2.4\bin")
        * MinGW (e.g., "C:\MinGW\bin")
        * Qt    (e.g., "C:\Qt\4.3.2\bin")

  2. Configure Vidalia and generate Makefiles by running: 

        mkdir build && cd build
        cmake -G "MinGW Makefiles" ..

     There should be no spaces in the path to your build directory. Otherwise,
     Vidalia will fail to build.

  3. Compile Vidalia by running: 
                          
        mingw32-make


If CMake fails to find your Qt installation, you can explicitly tell CMake
where to find Qt as in the following example:

        cmake -DQT_QMAKE_EXECUTABLE="C:\Qt\4.3.2\bin\qmake.exe" ..

You would replace "C:\Qt\4.3.2\bin" in the previous command with the actual
path to your Qt installation's qmake.exe binary.

If you are trying to build Vidalia for Windows 2000 and earlier, you should
download Windows SDK, copy wspiapi.h header to MinGW include directory and
build vidalia running:

        cmake -DWIN2K ..

Note: the header as it is in the SDK needs a "_inline" to be replaced to 
"__inline" for it to build properly.


Windows with Visual Studio
--------------------------
Starting with Qt 4.3.2, the open source editions of Qt/Win include support for
Visual Studio. Previously, Visual Studio support was limited to commercial 
editions of Qt unless you patched Qt's source.

To build Vidalia under Visual Studio, you will first need to obtain Qt's 
source code and compile it with Visual Studio support. The following
directions show how to compile Qt with Visual Studio 2005 support, but a
similar process can be followed for other versions of VS. 

  1. Download and install Visual C++ 2005 Express
 
       http://www.microsoft.com/express/2005/download/default.aspx

  2. Download and install the Windows Platform SDK and configure Visual C++ with
     the location of the Platform SDK's executable, include, and library
     directories.

       http://msdn2.microsoft.com/en-us/express/aa700755.aspx

     It is important to also install the "Microsoft Web Workshop (IE) SDK", even
     though that seems irrelevant.

  3. Download the Qt/Windows open source edition source code and extract it to a
     directory with no spaces (e.g., C:\Qt\4.3.3).

       http://qt.nokia.com/downloads/windows-cpp

  4. Edit the Visual Studio  2005 command prompt environment variables to
     include the platform SDK files, by opening

       C:\Program Files\Microsoft Visual Studio 8\Common7\Tools\vsvars32.bat

     and adding

       C:\Program Files\Microsoft Platform SDK for Windows Servers 2003 R2\Include

     to the INCLUDE variable and

       C:\Program Files\Microsoft Platform SDK for Windows Servers 2003 R2\Lib

     to the LIB variable. Modify the path to the platform SDK files as
     appropriate, depending on where you installed Visual Studio and the
     Platform SDK in Steps 1 and 2.

  5. Open the Visual Studio 2005 Command Prompt and 'cd' to the location of 
     your extracted Qt source code (e.g., C:\Qt\4.3.3).

  6. Configure Qt with support for your version of Visual Studio. For example,
     to configure Qt with support for Visual Studio 2005, you would run:

      configure.exe -debug-and-release -static -fast -platform win32-msvc2005

     See Qt's README file for more available platform options.

  7. Compile Qt by running:  
     
        nmake.exe
  
     (NOTE: This step will take several hours and lots of hard drive space.)
 
Once you have Qt compiled with Visual Studio support, you can use CMake to
generate a Visual Studio project file by running

        mkdir build && cd build
        cmake -G "Visual Studio 8 2005" ..

or whatever your particular version of Visual Studio happens to be.
'cmake --help' lists other available generators.


Windows with NMake
-------------------
To compile Vidalia from the command line using NMake, you will first need to
follow the steps under the 'Windows with Visual Studio' section for compiling
Qt with Visual Studio support.

If you want to build Vidalia from the command line, you can have CMake 
generate NMake makefiles by running:

        mkdir build && cd build
        cmake -G "NMake Makefiles" ..

You can then compile Vidalia from the command line by simply running:

        nmake


Available Configuration Options
-------------------------------
You can customize your Vidalia build by supplying arguments and values to the
`cmake` commands above. Each of the configuration options can be specified on
the command line and follows the format "-D <var>:<type>=<value>

  -DUSE_MINIUPNPC=0
    
    Disable UPnP support in Vidalia.

  -DOSX_FAT_BINARY=1 
    
    Build Vidalia as a Universal binary.

  -DOSX_TIGER_COMPAT=1
  
    Build Vidalia compatible with OS X Tiger (10.4).

  -DOSX_FORCE_32BIT=1

    Forces a 32-bit build. This is useful on platforms that default to 64-bit
    (e.g. Snow Leopard), but only have 32-bit versions of the Qt libraries
    available.

  -DQT_QMAKE_EXECUTABLE=/path/to/qmake
  
    Specifies the location of Qt's 'qmake' binary.

  -DOPENSSL_LIBRARY_DIR=/path/to/openssl
  
    Specifies the location of OpenSSL's libraries for building installer on 
    Windows.

  -DCMAKE_INSTALL_PREFIX=/usr/local
  
    Specifies the install prefix used for `make install`.

  -DCMAKE_BUILD_TYPE=<buildtype>
  
    Available build types include: "release", "debug", "minsizerel"

  -DUSE_MARBLE=1
  
    Replace the flat map with a 3-D sphere using the Marble libraries.

  -DWIX_BINARY_DIR=C:\Path\To\WiX\
  
    Specifies the location of your WiX executables, such as candle.exe and
    light.exe (optional, Windows-only).

  -DWIN2K

    Builds Vidalia using the inlines defined in wspiapi.h header for Windows
    2000 and earlier support.


For example, to configure CMake to look for Qt in "/usr/local/Qt-4.3.2/bin",
you would run:

      cmake -DQT_QMAKE_EXECUTABLE=/usr/local/Qt-4.3.2/bin/qmake ..

Don't forget the dot(s) at the end!

CMake also supports other generators besides Makefiles on certain platforms. 
See  'cmake --help' or 'man cmake' (on non-Windows platforms) for more 
information about supported generators and configuration options.


Additional Build Targets
-------------------------
Vidalia contains a number of additional CMake build targets to assist in
building code documentation and platform-specific packages. The targets are:

  'dist'                    Creates a Vidalia source code tarball.

  'dist-osx'                Creates a Vidalia-only Mac OS X .dmg.

  'dist-osx-bundle'         Creates a Vidalia bundle .dmg. See
                            pkg/osx/build-bundle.txt for additional
                            information on the CMake options necessary to create
                            a proper OS X bundle.

  'dist-osx-split-bundle'   Creates a "split" Mac OS X bundle. See 
                            pkg/osx/build-bundle.txt for additional
                            information on the CMake options necessary to create
                            a proper OS X bundle.

  'dist-win32'              Creates a Windows .msi package. You will also
                            need to define -DWIX_BINARY_DIR=<path-to-WiX>
                            in order to use this build target.

  'doxygen'                 Creates the Doxygen-generated code
                            documentation for Vidalia's source. You must
                            have Doxygen installed for this target to
                            function.

