root/vidalia/trunk/INSTALL

         Instruction for Building and Installing Vidalia from Source


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

  * Qt >= 4.2           http://trolltech.com/downloads/opensource
  * Tor >= 0.1.2.18     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:

                           cmake . && make
  
     [optional] CMake also supports out-of-source builds, so compiled and
     generated files are kept separate from the source tree. For example, you
     can create a build directory as follows:

                        mkdir build && cd build

     Instead of the 'cmake .' command listed above, you would configure and
     compile Vidalia by running:

                           cmake .. && make

  2. When the previous command finishes, Vidalia's binary will be
     placed in the 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:

                           cmake . && make

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

                           cmake -G Xcode .

  2. If you built from the command line, Vidalia's binary will be in an
     application bundle located at 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: 
    
                        cmake -G "MinGW Makefiles" .
    

  3. Compile Vidalia by running: 
                          
                            mingw32-make


If CMake fails to find your Qt installation, you can explicitly tell CMake
where to find Qt by running:

          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.


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://trolltech.com/developer/downloads/qt/windows

  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

                          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:

                     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_QSSLSOCKET=0                      Disable building Vidalia with SSL
                                          support.

  -DUSE_MINIUPNPC=0                       Disable UPnP support in Vidalia.

  -DOSX_FAT_BINARY=1                      Build Vidalia as a Universal binary.

  -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.

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


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 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.