###
### Instructions for building Tor Browser Bundle components
###
### Copyright 2007 Steven J. Murdoch <http://www.cl.cam.ac.uk/users/sjm217/>
### Copyright 2008 The Tor Project <https://www.torproject.org/>
### See LICENSE for licensing information
###

Contents
========

- Introduction to Building the Tor Browser Bundle
- Install Subversion
- Install 7zip
- Install Python
- Install MinGW (MinGW - Minimalist GNU for Windows)
- Install MSYS
- Install CMake
- Install Qt
- Install msysDTK
- Install WinRAR
- Building zlib
- Building OpenSSL
- Building libevent
- Building Tor
- Building Vidalia
- Unpacking PidginPortable
- Building Firefox or Unpacking Firefox Portable
- Adding extensions to Firefox Portable (3.6.x series)
- Customizing and Building the Tor Browser Bundle

An Introduction to Building Tor Browser Bundle
==============================================

To build Tor Browser Bundle, you need to have built:
 Vidalia (in /c/build/vidalia-<version> by default)
 Tor (in /c/build/tor-<version> by default)
and have uncompressed Firefox Portable or produce a custom build Firefox
 FirefoxPortable (in /c/build/FirefoxPortable by default)

Instructions for building Vidalia, and Tor are included below.

As a prerequisite for all builds, we'll need a build directory:

    cd C:\
    C:\>mkdir build

Vidalia needs to have the BrowserExecutable, ProxyExecutable,
RunProxyAtStart and ProxyExecutableArguments options. Currently this
is only available in the Vidalia trunk revision 2328 and later.

Furthermore, you'll need to install many different software packages for the
checkout and build process.  Sadly, many of these packages are unsigned and
there is very little in the way of a chain of trust.

Installing Subversion
=====================

To checkout the Tor Browser Bundle, you need Subversion.
You can download and install the stock Subversion package:

    http://subversion.tigris.org/getting.html

Specifically you should use the pre-built packages. You can choose any from
this list:

    http://subversion.tigris.org/servlets/ProjectDocumentList?folderID=91

Or if you'd like a direct link, you can use this as it is tested and working
for our purposes:

    http://subversion.tigris.org/files/documents/15/41686/svn-1.4.6-setup.exe

Alternatively, TortoiseSVN offers a graphical interface and integrates
with Windows Explorer:

 http://tortoisesvn.tigris.org/

Installing 7zip
===============

Download 7zip and install it. Possible choices for downloads are listed here:

    http://www.7-zip.org/download.html

Currently, 7-zip doesn't have package signatures, we requested this for current
and future releases:

    http://sourceforge.net/forum/message.php?msg_id=4982530

The suggested version is "7-Zip 4.57":

    http://downloads.sourceforge.net/sevenzip/7z457.exe

Installing MinGW
(MinGW - Minimalist GNU for Windows)
====================================

You need to install MinGW and then MSYS.
It's useful to read about these two projects:

  http://www.mingw.org/

For MinGW, download and run MinGW-5.1.6.
You can find the proper release on Sourceforge:

  http://sourceforge.net/projects/mingw/files/

To download MinGW-5.1.6.exe, visit the following URL:

  http://sourceforge.net/projects/mingw/files/Automated%20MinGW%20Installer/MinGW%205.1.6/MinGW-5.1.6.exe/download

Run MinGW-5.1.6.exe and begin the install. When prompted, select 'Full' as the
type of install.  If you know better, select individual packages. It is
expected that you will install MinGW into: C:\MinGW

Installing MSYS
===============

For tar and other useful commands, you will also need MSYS. The current version
of this is hellish to find.  In short, visit the MSYS Base System download
page:

  http://sourceforge.net/projects/mingw/files/

The MSYS-1.0.11.exe download url is:

  http://sourceforge.net/projects/mingw/files/MSYS%20Base%20System/msys-1.0.11/MSYS-1.0.11.exe/download

Download and install MSYS-1.0.11.exe. When prompted, read the license agreement
and other documentation.  When asked for an install path, choose: C:\msys\1.0

You will be prompted to do a post install process that will "normalize" your
MinGW environment with MSYS.  Agree to the prompt. You will hopefully see a
prompt that says:

    "Oh joy, you do not have C:MinGW/bin/make.exe. Keep it that way."

Read the MSYS README. Understanding how to use MSYS is important.

Now you'll need to fix your /etc/fstab because it is broken by default. Make it
look like so:

    Administrator@I-CF61A82488F14 /
    $ cat /etc/fstab
    C:\MinGW /mingw

Once you have replaced the three old binaries you will be ready to actually do
something useful.

All of the rest of the build commands will take place inside of the MSYS Shell.
Launch that now. It's found in:

    Start Menu -> All Programs -> MinGW -> MSYS -> msys

Installing GNU wget is optional. If you installed Python, you do not need to
install wget.  It is not required as basic wget functionality is implemented in
Python. Instructions for downloading, compiling and installing wget for MSYS
can be found here:

    http://www.mingw.org/MinGWiki/index.php/mingwPORT

Installing CMake
================

We'll need CMake to build Vidalia.

You can read about different versions on the CMake homepage:

  http://cmake.org/

Download version 2.8.0:

  http://www.cmake.org/files/v2.8/cmake-2.8.0-win32-x86.exe

Run the installer with Windows Explorer and install into:

    'C:\Program Files\CMake 2.8'

Installing Qt
=============

Download Qt 4.3 or later, we'll use 4.6.2:

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

Download and run the installer with Windows Explorer:

  http://get.qt.nokia.com/qt/source/qt-win-opensource-4.6.2-mingw.exe

When prompted, install Qt into 'C:\Qt\4.6.2'
You will be prompted for the install path for your MinGW directory, enter 'C:\MinGW'
You may have an error about win32api.h being not found. This is not true. You
have win32api.h and Qt is wrong.  This is a result of the Qt installer not
understanding how to count version numbers. This is probably fixed in newer
versions of Qt. YMMV.

Installing msysDTK
==================

In short, you'll now need to install the msysDTK:

    http://prdownloads.sf.net/mingw/msysDTK-1.0.1.exe?download

Run msysDTK-1.0.1.exe and install it into C:\msys\1.0

This will give you Perl, which is necessary for the OpenSSL build

Installing autoconf update
==========================

Now you'll download download the mingw autoconf-2.59 update:

    http://prdownloads.sf.net/mingw/msys-autoconf-2.59.tar.bz2?download

Extract the .tar.gz like so in your MSYS console:

    tar -C / -xvjf /c/Documents\ and\ Settings/Administrator/Desktop/msys-autoconf-2.59.tar.bz2

Building zlib
=============

Now we'll download zlib and install it.

Download the zlib source:
        http://www.zlib.net/zlib-1.2.3.tar.gz

Currently, zlib doesn't have package signatures. We emailed the zlib team and are awaiting a reply.

Extract zlib:
        $ cd /c/build/
        $ tar -C /c/build/ -xvzf /c/Documents\ and\ Settings/Administrator/Desktop/zlib-1.2.3.tar.gz
        $ cd zlib-1.2.3/

Build it (we'll need this because we want zlib.a):
        ./configure
        make
        make install

Building OpenSSL
================

Download openssl:

    http://www.openssl.org/source/openssl-0.9.8l.tar.gz

Unpack it:

    cd /c/build/
    tar -C /c/build/ -xvzf /c/Documents\ and\ Settings/Administrator/Desktop/openssl-0.9.8l.tar.gz

You should see errors not unlike:

    tar: openssl-0.9.8l/include/openssl/bn.h: Cannot create symlink to `../../crypto/bn/bn.h': No such file or directory
    tar: openssl-0.9.8l/include/openssl/blowfish.h: Cannot create symlink to `../../crypto/bf/blowfish.h': No such file or directory
    tar: openssl-0.9.8l/include/openssl/bio.h: Cannot create symlink to `../../crypto/bio/bio.h': No such file or directory
    tar: openssl-0.9.8l/include/openssl/asn1t.h: Cannot create symlink to `../../crypto/asn1/asn1t.h': No such file or directory
    tar: openssl-0.9.8l/include/openssl/asn1_mac.h: Cannot create symlink to `../../crypto/asn1/asn1_mac.h': No such file or directory
    tar: openssl-0.9.8l/include/openssl/asn1.h: Cannot create symlink to `../../crypto/asn1/asn1.h': No such file or directory
    tar: openssl-0.9.8l/include/openssl/aes.h: Cannot create symlink to `../../crypto/aes/aes.h': No such file or directory
    tar: openssl-0.9.8l/apps/md4.c: Cannot create symlink to `../crypto/md4/md4.c': No such file or directory
    tar: Error exit delayed from previous errors

Uncompressing OpenSSL shows a number of errors concerning symlinks. These do
not appear to have caused a problem.

Now configure the source package:

    cd openssl-0.9.8l/
    ./config -no-idea -no-rc5 -no-mdc2

Edit '/c/build/openssl-0.9.8l/Makefile' and remove the "test:" and "tests:" sections that follow:

    test:   tests

    tests: rehash
            @(cd test && echo "testing..." && \
            $(CLEARENV) && $(MAKE) -e $(BUILDENV) TOP=.. TESTS='${TESTS}' OPENSSL_DE
    BUG_MEMORY=on tests );
            util/opensslwrap.sh version -a

Now remove things we don't need that interfere with the build process:

        rm -rf ./test

Now copy files we do need:

        cd crypto/
        find ./ -name "*.h" -exec cp {} ../include/openssl/ \;
        cd ../ssl/
        find ./ -name "*.h" -exec cp {} ../include/openssl/ \;
        cd ..
        cp *.h include/openssl/
        cp fips/fips.h include/openssl/

And finally, build it - this can take a long time and depends on the speed of your computer:

        make
        make install

Building libevent
=================

Next, you'll want to download, unpack, build and install libevent (Version: libevent-1.4.13).
You can get libevent here:

        http://www.monkey.org/~provos/libevent/
        http://www.monkey.org/~provos/libevent-1.4.13-stable.tar.gz
        http://www.monkey.org/~provos/libevent-1.4.13-stable.tar.gz.sig

Verify the signature.

Unpack it:

    tar -C /c/build/ -xvzf /c/Documents\ and\ Settings/Administrator/Desktop/libevent-1.4.13-stable.tar.gz
    cd libevent-1.4.13-stable/

Configure, build and install:

    ./configure --enable-static --disable-shared
    make
    make install

Building Tor
============

Download, unpack, build and install Tor:
        https://www.torproject.org/download.html
        https://www.torproject.org/dist/tor-0.2.1.26.tar.gz
        https://www.torproject.org/dist/tor-0.2.1.26.gz.asc
        $ cd /c/build/
        tar -C /c/build -xvzf /c/Documents\ and\ Settings/Administrator/Desktop/tor-0.2.1.26.tar.gz
        $ cd tor-0.2.1.26/
        ./configure
        make

Building Vidalia
================

To use QSslSocket for GeoIP lookups, install OpenSSL before building
Vidalia (see above).

Download Vidalia:

    https://www.torproject.org/vidalia/dist/vidalia-0.2.9.tar.gz
    https://www.torproject.org/vidalia/dist/vidalia-0.2.9.tar.gz.asc

Verify the signature.

Unpack Vidalia:

    tar -C /c/build/ -xvzf /c/Documents\ and\ Settings/Administrator/Desktop/vidalia-0.2.9.tar.gz
    mv vidalia-0.2.9/ vidalia

Set a proper environment:

    cat << 'EOF' >> /etc/profile
    export QTDIR="C:\Qt\4.6.2"
    export PATH=$PATH:/c/Qt/4.6.2/bin
    export PATH=$PATH:/c/Program\ Files/CMake\ 2.8/bin/
    export QMAKESPEC=win32-g++
    EOF

    export PATH=$PATH:/c/Program\ Files/CMake\ 2.8/bin/:/c/MinGW/bin/:/c/Qt/4.6.2/bin/

Create the proper MSYS Makefiles and don't forget the '.' at the end!

    cd /c/build/vidalia
    cmake -G "MSYS Makefiles" .

You may see some errors:

    -- Check size of int - done
    -- Configuring done
    CMake Warning (dev) at src/vidalia/CMakeLists.txt:229 (add_executable):
      Policy CMP0003 should be set before this line.  Add code such as

        if(COMMAND cmake_policy)
          cmake_policy(SET CMP0003 NEW)
        endif(COMMAND cmake_policy)

      as early as possible but after the most recent call to
      cmake_minimum_required or cmake_policy(VERSION).  This warning appears
      because target "vidalia" links to some libraries for which the linker must
      search:

        imm32, winmm, ws2_32, ole32, oleaut32, uuid, winspool, ole32, oleaut32
        uuid, winspool

      and other libraries with known full path:

        C:/Qt/4.5.2/lib/libQtGui4.a


      CMake is adding directories in the second list to the linker search path in
      case they are needed to find libraries from the first list (for backwards
      compatibility with CMake 2.4).  Set policy CMP0003 to OLD or NEW to enable
      or disable this behavior explicitly.  Run "cmake --help-policy CMP0003" for
      more information.
    This warning is for project developers.  Use -Wno-dev to suppress it.

    -- Generating done
    -- Build files have been written to: C:/build/vidalia

This is OK. You can ignore these errors.

Now you'll build Vidalia by running MSYS make:

    cd /c/build/vidalia/
    make

Alternatively building under MinGW32
====================================

If you decide to not build with MSYS as mentioned above, you can use MinGW32 to build Vidalia.

Qt and CMake must be in the %PATH%. An easy way to do this is to
copy qtvars.bat and add the path to CMake. Then, copy the shortcut
from the Start menu, and edit the path to point to the altered
qtvars.bat

Then run:
 > cmake -G "MinGW Makefiles" .
 > mingw32-make

Further information
===================

Full instructions are in the Vidalia INSTALL file.

Unpacking PidginPortable
========================

Download PidginPortable from:
 http://portableapps.com/apps/internet/pidgin_portable

Also download the portable Pidgin-OTR plugin from the same page.

Install both to C:\build\PidginPortable-<version>

When installing Pidgin Portable, choose to install the extra language
packs.

Building Firefox
================

Currently the Tor Browser Bundle uses FirefoxPortable binaries.

Download FirefoxPortable:

    http://prdownloads.sourceforge.net/portableapps/FirefoxPortable_3.5.10_English.paf.exe

Run the installer and select it into: 'C:\build\FirefoxPortable-<version>'

If you use FirefoxPortable, you can skip past the following build steps and go directly to the customization section.

Eventually it should use a custom build of Firefox. The following is a set of notes on building Firefox.

Adding extensions to Firefox Portable
=====================================

To ship extensions with Firefox (Portable or otherwise) on Windows, do the following:
- Create a directory in FirefoxPortable/App/Firefox/distribution/bundles.
- Download the extensions you want into this directory. Currently the Tor
  Browser Bundle is using Torbutton, HTTPS Everywhere, Better Privacy, and NoScript 
- Make directories named after the extension ID of the extension. For
  Torbutton, this is {e0204bd5-9d31-402b-a99d-a6aa8ffebdca}. The others can be
  found inside their respective .xpis, in install.rdf.
- Copy the .xpi into the directory with its extension ID and unzip it with 7zip.

Tested compilers for building Firefox
=====================================

MinGW32 cross compile under Linux:
 Failed to work (unsupported by Mozilla)
MSVC 8 (Visual Studio .NET 2005):
 Failed to work (unsupported by Mozilla for Firefox 2, but should work
 for Firefox >=3)
 With some patches it may be possible to build Firefox 2:
  http://georgedexter.wordpress.com/2007/03/03/building-firefox-2002-on-windows/
MSVC 7.1 (Visual Studio .NET 2003):
 Works, provided  msvcp71.dll and msvcr71.dll are copied

For more information see:
 http://developer.mozilla.org/en/docs/Windows_Build_Prerequisites
 http://developer.mozilla.org/en/docs/Build_and_Install

Instructions building Firefox with MSVC 7.1
===========================================

- Install MSVC 7.1 (Visual Studio .NET 2003) and upgrade using Microsoft Update

- Download Platform SDK from
  http://www.microsoft.com/downloads/details.aspx?familyid=0baf2b35-c656-4969-ace8-e4c0c0716adb

- Install MozillaBuild from
  http://ftp.mozilla.org/pub/mozilla.org/mozilla/libraries/win32/MozillaBuildSetup-1.1.exe

- Run e:\mozilla-build\start-msvc8.bat

  $ cd "e:\mozilla\build"
  $ tar -xjvf ../firefox-2.0.0.9-source.tar.bz2
  $ cd mozilla
  [ dot_mozconfg is in config/ ]
  $ cp ../dot_mozconfig .mozconfig
  $ make -f client.mk build

- Copy msvcp71.dll and msvcr71.dll from "Microsot Visual Studio .NET 2003\Visual
  Studio .NET Professional 2003 - English" to obj-i686-pc-mingw32\dist\bin

- Add "msvcp71.dll" and "msvcr71.dll" to browser/installer/windows/packages-static

$ make -C obj-i686-pc-mingw32/browser/installer

Customization
=============

The locations of Qt, MinGW32, the Vidalia/Tor build directory, 7zip,
FirefoxPortable can be altered in Makefile. The WGET variable should
be set to the location of a wget binary.

Building the Tor Browser Bundle
===============================

Now you'll want to ensure you have the Tor Browser Bundle code checked out into C:\build\

    C:\build>svn co https://svn.torproject.org/svn/torbrowser/

Firefox must not be running while you are building the bundle.
If you're using different versions than the Makefile, you'll want to patch the
Makefile as mentioned in the Customization section above.

An example to change the Qt Lib version:

        From: QT=/c/Qt/4.6.2/bin
        To: QT=/c/Qt/4.6.2/bin

And then change the Tor version:

        From: TOR=/c/build/tor-0.2.1.26
        To: TOR=/c/build/tor-0.2.1.26

Now you can run "make bundle_LANGUAGE", e.g. "make bundle_en-US".

Alternatively, to build a compressed executable version, run "make
compressed-bundle_LANGUAGE", e.g. "make compressed-bundle_de".

Currently supported language codes are:
 - ar
 - en-US
 - de
 - es-ES
 - fa-IR
 - fr
 - it
 - nl
 - pl
 - pt-PT
 - ru
 - vi
 - zh-CN

New languages can be added by finding out the appropriate Mozilla
language pack code from:

    http://releases.mozilla.org/pub/mozilla.org/firefox/releases/3.5.10/win32/xpi

If the Mozilla code differs from the Vidalia one, update
patch-vidalia-language.sh accordingly.


