[or-cvs] r18661: {torvm} Add Windows build setup documentation; build cleanup. (in torvm/trunk: build/win32 build/win32/files doc doc/devel doc/devel/img)

coderman at seul.org coderman at seul.org
Sat Feb 21 05:43:40 UTC 2009 

Author: coderman
Date: 2009-02-21 00:43:40 -0500 (Sat, 21 Feb 2009)
New Revision: 18661

Added:
   torvm/trunk/doc/devel/
   torvm/trunk/doc/devel/buildsetup.html
   torvm/trunk/doc/devel/buildsetup.xml
   torvm/trunk/doc/devel/img/
   torvm/trunk/doc/devel/img/bldrun1.png
   torvm/trunk/doc/devel/img/bldrun2.png
   torvm/trunk/doc/devel/img/ddkinst1.png
   torvm/trunk/doc/devel/img/ddkinst2.png
   torvm/trunk/doc/devel/img/ddkinst3.png
   torvm/trunk/doc/devel/img/ddkinst4.png
   torvm/trunk/doc/devel/img/ddkinst5.png
   torvm/trunk/doc/devel/img/ddkinst6.png
   torvm/trunk/doc/devel/img/ddkinst7.png
   torvm/trunk/doc/devel/img/ddkinst8.png
   torvm/trunk/doc/devel/img/ddkinst9.png
   torvm/trunk/doc/devel/img/setup1.png
   torvm/trunk/doc/devel/img/setup2.png
   torvm/trunk/doc/devel/img/setup3.png
   torvm/trunk/doc/devel/img/setup4.png
   torvm/trunk/doc/devel/img/vsinst1.png
   torvm/trunk/doc/devel/img/vsinst10.png
   torvm/trunk/doc/devel/img/vsinst11.png
   torvm/trunk/doc/devel/img/vsinst12.png
   torvm/trunk/doc/devel/img/vsinst13.png
   torvm/trunk/doc/devel/img/vsinst2.png
   torvm/trunk/doc/devel/img/vsinst3.png
   torvm/trunk/doc/devel/img/vsinst4.png
   torvm/trunk/doc/devel/img/vsinst5.png
   torvm/trunk/doc/devel/img/vsinst6.png
   torvm/trunk/doc/devel/img/vsinst7.png
   torvm/trunk/doc/devel/img/vsinst8.png
   torvm/trunk/doc/devel/img/vsinst9.png
Modified:
   torvm/trunk/build/win32/Makefile
   torvm/trunk/build/win32/files/buildall.sh
Log:
Add Windows build setup documentation; build cleanup.

Modified: torvm/trunk/build/win32/Makefile
===================================================================
--- torvm/trunk/build/win32/Makefile	2009-02-21 00:28:23 UTC (rev 18660)
+++ torvm/trunk/build/win32/Makefile	2009-02-21 05:43:40 UTC (rev 18661)
@@ -243,7 +243,7 @@
   ALLFILES+=$(SEVNZIP_F)
   SEVNZIP_OPT_DL=if [ ! -e $(WDLDIR)/$(SEVNZIP_F) ]; then $(DLCMD) "$(SEVNZIP_URL)" $(SEVNZIP_SUM) "$(WDLDIR)/$(SEVNZIP_F)"; fi
   ifeq (true,$(SEVNZIP_INST))
-    SEVNZIP_OPT_PKG=dl/$(SEVNZIP_F)
+    SEVNZIP_OPT_PKG=$(SEVNZIP_F)
   endif
 endif
 

Modified: torvm/trunk/build/win32/files/buildall.sh
===================================================================
--- torvm/trunk/build/win32/files/buildall.sh	2009-02-21 00:28:23 UTC (rev 18660)
+++ torvm/trunk/build/win32/files/buildall.sh	2009-02-21 05:43:40 UTC (rev 18661)
@@ -243,12 +243,12 @@
   anyfail=0
   echo "Checking for any packages to install..."
   if [[ "$SEVNZIP_INST" == "true" ]]; then
-    if [ ! -f "/${SEVNZIP_PKG}" ]; then
+    if [ ! -f "/dl/${SEVNZIP_PKG}" ]; then
       echo "ERROR: Unable to locate expected 7zip package for install at location: /${SEVNZIP_PKG}"
       anyfail=1
     else
-      echo "Attempting to install ${MSYSROOT}\\${SEVNZIP_PKG} ..."
-      $COMSPEC /k "msiexec /i ${MSYSROOT}\\${SEVNZIP_PKG} /qn" < /dev/null
+      echo "Attempting to install ${MSYSROOT}\\dl\\${SEVNZIP_PKG} ..."
+      $COMSPEC /k "msiexec /i ${MSYSROOT}\\dl\\${SEVNZIP_PKG} /qn" < /dev/null
       # XXX need to check for failure to install properly via exit code and package status.
     fi
   fi
@@ -355,6 +355,7 @@
       exit 1
     fi
   )
+  cp *.dll $libdir/
 
   pkgbuilt ZLIB_BUILT
 fi
@@ -970,25 +971,6 @@
     echo "ERROR: unable to build self extracting Tor VM archive."
   fi
 
-  echo "Creating vidalia exe self-extracting archive ..."
-  mkdir vidalia-exes
-  cp bin/vidalia-2d.exe vidalia-exes/
-  cp bin/vidalia-marble.exe vidalia-exes/
-  export exename=VidaliaExes.exe
-  if [ -f $exename ]; then
-    rm -f $exename
-  fi
-  7z.exe a -sfx7z.sfx $exename vidalia-exes
-  if [ -f $exename ]; then
-    cp $exename $bundledir
-    ls -l $exename
-  else
-    echo "ERROR: unable to build self extracting Tor VM archive."
-  fi
-
-  echo "Creating vidalia exe self-extracting archive ..."
-  
-
   pkgbuilt PACKAGES_BUILT
 fi
 

Added: torvm/trunk/doc/devel/buildsetup.html
===================================================================
--- torvm/trunk/doc/devel/buildsetup.html	                        (rev 0)
+++ torvm/trunk/doc/devel/buildsetup.html	2009-02-21 05:43:40 UTC (rev 18661)
@@ -0,0 +1,211 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Windows Build Environment</title><meta name="generator" content="DocBook XSL Stylesheets V1.68.1" /></head><body><div class="article" lang="en" xml:lang="en"><div class="titlepage"><div><div><h1 class="title"><a id="win32buildsetup"></a>Windows Build Environment</h1></div><div><div class="author"><h3 class="author"><span class="firstname">Martin</span> <span class="surname">Peck</span></h3><div class="affiliation"><div class="address"><p><code class="email">&lt;<a href="mailto:coderman at gmail dot com">coderman at gmail dot com</a>&gt;</code></p></div></div></div></div><div><p class="copyright">Copyright © 2009 The Tor Project, Inc.</p></div><div><p class="pubdate">February 20, 2009</p></div></div><hr /></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#id2486682">1. Introduction</a></span></dt><dd><dl><dt><span class="sect2"><a href="#buildintegrity">1.1. Build Automation and Integrity</a></span></dt><dt><span class="sect2"><a href="#vmbuildhosts">1.2. Virtual Machine Guest Builds</a></span></dt></dl></dd><dt><span class="sect1"><a href="#id2465311">2. Build Setup</a></span></dt><dd><dl><dt><span class="sect2"><a href="#prereqs">2.1. Prerequisites</a></span></dt><dt><span class="sect2"><a href="#basicsetup">2.2. Basic Windows VM Setup</a></span></dt><dt><span class="sect2"><a href="#ddkinstall">2.3. Install Driver Development Kit</a></span></dt><dt><span class="sect2"><a href="#installvcpp">2.4. Install Visual C++ Express Edition</a></span></dt><dt><span class="sect2"><a href="#vmcheckpoint">2.5. SAVE YOUR WINDOWS VIRTUAL DISK IMAGE AT THIS POINT</a></span></dt></dl></dd><dt><span class="sect1"><a href="#id2455668">3. Running Builds</a></span></dt><dd><dl><dt><span class="sect2"><a href="#runfullbuild">3.1. Launch Full Build</a></span></dt><dt><span class="sect2"><a href="#runpartbuild">3.2. Partial and Development Builds</a></span></dt><dt><span class="sect2"><a href="#msysenv">3.3. MSYS Development Tools</a></span></dt></dl></dd><dt><span class="sect1"><a href="#id2455789">4. Legal Notice</a></span></dt></dl></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2486682"></a>1. Introduction</h2></div></div></div><p>
+This document describes the Windows system configuration and package installation required for
+ building the Tor VM packages.
+  </p><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="buildintegrity"></a>1.1. Build Automation and Integrity</h3></div></div></div><p>
+Fully automated builds provide a number of benefits to the development life cycle including
+ frequent binary releases and integration with automated test harnesses. An automated build
+ can also improve the compilation and packaging of production ready releases for public
+ distribution.
+   </p><p>
+Assuming no network resources are necessary during builds a known good Windows installation
+ coupled with the same set of build sources should always produce a functionally
+ equivalent set of application binaries and libraries. [note: due to the nature of linking
+ on win32 platforms, and possibly other reasons, it is unlikely that two builds of the same
+ application image will result in identical binaries with identical checksums.]
+   </p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="vmbuildhosts"></a>1.2. Virtual Machine Guest Builds</h3></div></div></div><p>
+Windows virtual machines are used to build the Tor VM packages inside a guest OS instance
+ to achieve the integrity and automation desired in a reliable software distribution system.
+   </p><p>
+It is recommended that a clean installation from source media be performed on a new VM image
+ to ensure that virtual disks used for builds are void of any conflicting or malicious code.
+   </p></div></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2465311"></a>2. Build Setup</h2></div></div></div><p>
+The instructions below will prepare a minimal Windows XP build host environment sufficient to
+ run the Tor VM build ISO image and packaging.
+  </p><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="prereqs"></a>2.1. Prerequisites</h3></div></div></div><p>
+You will require the following:
+   </p><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id2465334"></a>A Windows Operating System</h4></div></div></div><div class="itemizedlist"><ul type="disc"><li><span><strong class="command">Windows XP</strong></span><p>
+Windows XP is the suggested build host OS. Saving an image without upgrading service packs is
+recommended in case testing service pack incompatibilities becomes necessary.
+      </p></li><li><span><strong class="command">Windows 2000 SP2</strong></span><p>
+Windows 2000 with at least Service Pack 2 (SP2) may also be used for builds.
+      </p></li><li><span><strong class="command">Windows Vista</strong></span><p>
+Vista is NOT recommended. The new win32 APIs are not backward compatible with 2k or XP
+ and may produce builds linked to these interfaces.
+      </p></li></ul></div></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id2457287"></a>Microsoft Development Tools</h4></div></div></div><div class="itemizedlist"><ul type="disc"><li><span><strong class="command"><a href="http://download.microsoft.com/download/9/0/f/90f019ac-8243-48d3-91cf-81fc4093ecfd/1830_usa_ddk.iso" target="_top">Windows Driver Development Kit</a> (231 MBytes)</strong></span></li><li><span><strong class="command"><a href="http://www.microsoft.com/express/download/offline.aspx" target="_top">Visual Studio Express Edition DVD</a> (749 MBytes)</strong></span></li></ul></div></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="basicsetup"></a>2.2. Basic Windows VM Setup</h3></div></div></div><p>
+Changing the display to 16bit color depth may conserve resources and is more amenable
+ to most virtual machine software like VM Ware or VirtualBox.
+     </p><div class="mediaobject"><img src="img/setup1.png" /></div><p>
+   </p><div class="literallayout"><p><br />
+<br />
+   </p></div><p>
+Disable the screensaver and sleep modes.
+     </p><div class="mediaobject"><img src="img/setup2.png" /></div><p>
+   </p><div class="literallayout"><p><br />
+<br />
+   </p></div><p>
+Disable automatic updates. It is recommended that you manage updates offline in the
+ source OS images and not in temporal build host instances.
+     </p><div class="mediaobject"><img src="img/setup3.png" /></div><p>
+   </p><div class="literallayout"><p><br />
+<br />
+   </p></div><p>
+The indexing service is not necessary.
+     </p><div class="mediaobject"><img src="img/setup4.png" /></div><p>
+   </p><div class="literallayout"><p><br />
+<br />
+   </p></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="ddkinstall"></a>2.3. Install Driver Development Kit</h3></div></div></div><p>
+This ISO image has the annoying autorun behavior of launching IE to browse a readme.
+ You will need to "Explore" the CDROM rather than double click or open it.
+     </p><div class="mediaobject"><img src="img/ddkinst1.png" /></div><p>
+   </p><div class="literallayout"><p><br />
+<br />
+   </p></div><p>
+Run the setup program.
+     </p><div class="mediaobject"><img src="img/ddkinst2.png" /></div><p>
+   </p><div class="literallayout"><p><br />
+<br />
+   </p></div><p>
+A graphical installer is provided.
+     </p><div class="mediaobject"><img src="img/ddkinst3.png" /></div><p>
+   </p><div class="literallayout"><p><br />
+<br />
+   </p></div><p>
+
+     </p><div class="mediaobject"><img src="img/ddkinst4.png" /></div><p>
+   </p><div class="literallayout"><p><br />
+<br />
+   </p></div><p>
+Accept the default location for the install. Do not change the destination.
+     </p><div class="mediaobject"><img src="img/ddkinst5.png" /></div><p>
+   </p><div class="literallayout"><p><br />
+<br />
+   </p></div><p>
+Documentation is not necessary.
+     </p><div class="mediaobject"><img src="img/ddkinst6.png" /></div><p>
+   </p><div class="literallayout"><p><br />
+<br />
+   </p></div><p>
+The installation will consume about 700 MBytes of disk space.
+     </p><div class="mediaobject"><img src="img/ddkinst7.png" /></div><p>
+   </p><div class="literallayout"><p><br />
+<br />
+   </p></div><p>
+
+     </p><div class="mediaobject"><img src="img/ddkinst8.png" /></div><p>
+   </p><div class="literallayout"><p><br />
+<br />
+   </p></div><p>
+
+     </p><div class="mediaobject"><img src="img/ddkinst9.png" /></div><p>
+   </p><div class="literallayout"><p><br />
+<br />
+   </p></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="installvcpp"></a>2.4. Install Visual C++ Express Edition</h3></div></div></div><p>
+When the Visual Studio DVD is loaded a setup program should launch automatically
+ via Autorun.
+     </p><div class="mediaobject"><img src="img/vsinst1.png" /></div><p>
+   </p><div class="literallayout"><p><br />
+<br />
+   </p></div><p>
+Select Visual C++ 2008 Express Edition for installation.
+     </p><div class="mediaobject"><img src="img/vsinst2.png" /></div><p>
+   </p><div class="literallayout"><p><br />
+<br />
+   </p></div><p>
+
+     </p><div class="mediaobject"><img src="img/vsinst3.png" /></div><p>
+   </p><div class="literallayout"><p><br />
+<br />
+   </p></div><p>
+Step through the Visual C++ install process.
+     </p><div class="mediaobject"><img src="img/vsinst4.png" /></div><p>
+   </p><div class="literallayout"><p><br />
+<br />
+   </p></div><p>
+
+     </p><div class="mediaobject"><img src="img/vsinst5.png" /></div><p>
+   </p><div class="literallayout"><p><br />
+<br />
+   </p></div><p>
+The Silverlight Runtime and SQL Server components should not be installed.
+     </p><div class="mediaobject"><img src="img/vsinst6.png" /></div><p>
+   </p><div class="literallayout"><p><br />
+<br />
+   </p></div><p>
+Accept the default destination.
+     </p><div class="mediaobject"><img src="img/vsinst7.png" /></div><p>
+   </p><div class="literallayout"><p><br />
+<br />
+   </p></div><p>
+
+     </p><div class="mediaobject"><img src="img/vsinst8.png" /></div><p>
+   </p><div class="literallayout"><p><br />
+<br />
+   </p></div><p>
+Part way through installation you will need to restart the operating system.
+     </p><div class="mediaobject"><img src="img/vsinst9.png" /></div><p>
+   </p><div class="literallayout"><p><br />
+<br />
+   </p></div><p>
+
+     </p><div class="mediaobject"><img src="img/vsinst10.png" /></div><p>
+   </p><div class="literallayout"><p><br />
+<br />
+   </p></div><p>
+Once the OS has restarted the installation process will continue.
+     </p><div class="mediaobject"><img src="img/vsinst11.png" /></div><p>
+   </p><div class="literallayout"><p><br />
+<br />
+   </p></div><p>
+
+     </p><div class="mediaobject"><img src="img/vsinst12.png" /></div><p>
+   </p><div class="literallayout"><p><br />
+<br />
+   </p></div><p>
+It can take quite a few minutes for the install to complete.
+     </p><div class="mediaobject"><img src="img/vsinst13.png" /></div><p>
+   </p><div class="literallayout"><p><br />
+<br />
+   </p></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="vmcheckpoint"></a>2.5. SAVE YOUR WINDOWS VIRTUAL DISK IMAGE AT THIS POINT</h3></div></div></div><p>Once the necessary software is installed you should shutdown the Windows guest OS
+ and make a backup of the virtual disk image file. You should always build release packages
+ on a clean virtual disk restored from an authenticated backup image.</p></div></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2455668"></a>3. Running Builds</h2></div></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="runfullbuild"></a>3.1. Launch Full Build</h3></div></div></div><p>
+When the build ISO is loaded into a running system with Autorun enabled the build will
+ start automatically.
+     </p><div class="mediaobject"><img src="img/bldrun1.png" /></div><p>
+   </p><div class="literallayout"><p><br />
+<br />
+   </p></div><p>
+The install.bat script on the ISO disc can also be invoked directly to start
+ a build.
+     </p><div class="mediaobject"><img src="img/bldrun2.png" /></div><p>
+   </p><div class="literallayout"><p><br />
+<br />
+   </p></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="runpartbuild"></a>3.2. Partial and Development Builds</h3></div></div></div><p>
+It is often useful to have a build host with most of the common software and toolchain
+ already prepared and only the latest versions of a particular package are desired.
+   </p><p>
+Select the package(s) you wish to build frequently and launch an ISO build with the
+ appropriate PACKAGE_BUILT=yes in your environment before running install.bat.
+   </p><p>
+Save this virtual disk image and use it whenever just that software needs
+ building. This method of builds is more suitable for a development buildbot following
+ source commits than the full build of all tools and packages.
+   </p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="msysenv"></a>3.3. MSYS Development Tools</h3></div></div></div><p>
+The build ISO will install a number of MinGW32 and MSYS tools into C:\msys\1.0\. Run the
+ C:\msys\1.0\msys.bat script to start a shell terminal.
+   </p><p>
+Sources are in the /src/ directory in the msys environment and the buildall.sh script is
+ used to script the process process.
+   </p><p>
+Run "/src/buildall.sh shell" for a new login shell with all of the PATH and environment
+ prepared for individual package builds and development.
+   </p></div></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2455789"></a>4. Legal Notice</h2></div></div></div><p>
+You may distribute or modify this document according to the terms of the <a href="http://www.gnu.org/licenses/fdl-1.2.txt" target="_top">GNU Free Documentation License Version 1.2 or later</a>.
+  </p><p>
+"<span class="trademark">Tor</span>® is a registered trademark of The Tor Project, Inc."
+  </p><p>
+"<span class="trademark">VMware</span>® is a registered trademark of VMware, Inc. in the United States and other jurisdictions."
+  </p><p>
+"<span class="trademark">Windows</span>® is a registered trademark of Microsoft Corporation in the United States and other countries."
+  </p></div></div></body></html>

Added: torvm/trunk/doc/devel/buildsetup.xml
===================================================================
--- torvm/trunk/doc/devel/buildsetup.xml	                        (rev 0)
+++ torvm/trunk/doc/devel/buildsetup.xml	2009-02-21 05:43:40 UTC (rev 18661)
@@ -0,0 +1,474 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "file:///usr/share/docbook-xml-4.5/docbookx.dtd" >
+
+<!-- apply docbook stylesheet for html:
+ 
+ xsltproc ˗˗output buildsetup.html \
+   ˗˗stringparam section.autolabel.max.depth 2 \
+   ˗˗stringparam section.autolabel 1 \
+   .../path/to/docbook/4.5/xhtml/docbook.xsl buildsetup.xml
+
+--> 
+   
+<article id="win32buildsetup">
+ <articleinfo>
+  <title>Windows Build Environment</title>
+   
+   <author>
+    <firstname>Martin</firstname><surname>Peck</surname>
+    <affiliation>
+     <address><email>coderman at gmail dot com</email></address>
+    </affiliation>
+   </author>
+ 
+   <pubdate>February 20, 2009</pubdate>
+   <copyright>
+     <year>2009</year>
+     <holder>The Tor Project, Inc.</holder>
+   </copyright>
+ </articleinfo>
+
+
+
+<sect1>
+  <title>Introduction</title>
+  <para>
+This document describes the Windows system configuration and package installation required for
+ building the Tor VM packages.
+  </para>
+
+  <sect2 id="buildintegrity">
+   <title>Build Automation and Integrity</title>
+   <para>
+Fully automated builds provide a number of benefits to the development life cycle including
+ frequent binary releases and integration with automated test harnesses. An automated build
+ can also improve the compilation and packaging of production ready releases for public
+ distribution.
+   </para>
+   <para>
+Assuming no network resources are necessary during builds a known good Windows installation
+ coupled with the same set of build sources should always produce a functionally
+ equivalent set of application binaries and libraries. [note: due to the nature of linking
+ on win32 platforms, and possibly other reasons, it is unlikely that two builds of the same
+ application image will result in identical binaries with identical digests.]
+   </para>
+  </sect2>
+
+  <sect2 id="vmbuildhosts">
+   <title>Virtual Machine Guest Builds</title>
+   <para>
+Windows virtual machines are used to build the Tor VM packages inside a guest OS instance
+ to achieve the integrity and automation desired in a reliable software distribution system.
+   </para>
+   <para>
+It is recommended that a clean installation from source media be performed on a new VM image
+ to ensure that virtual disks used for builds are void of any conflicting or malicious code.
+   </para>
+  </sect2>
+
+</sect1>
+
+
+<sect1>
+  <title>Build Setup</title>
+  <para>
+The instructions below will prepare a minimal Windows XP build host environment sufficient to
+ run the Tor VM build ISO image and packaging.
+  </para>
+
+
+  <sect2 id="prereqs">
+   <title>Prerequisites</title>
+   <para>
+You will require the following:
+   </para>
+
+    <sect3>
+     <title>A Windows Operating System</title>
+     <itemizedlist>
+   
+      <listitem><command>Windows XP</command>
+      <para>
+Windows XP is the suggested build host OS. Saving an image without upgrading service packs is
+recommended in case testing service pack incompatibilities becomes necessary.
+      </para>
+      </listitem>
+
+      <listitem><command>Windows 2000 SP2</command>
+      <para>
+Windows 2000 with at least Service Pack 2 (SP2) may also be used for builds.
+      </para>
+      </listitem>
+
+      <listitem><command>Windows Vista</command>
+      <para>
+Vista is NOT recommended. The new win32 APIs are not backward compatible with 2k or XP
+ and may produce builds linked to these interfaces.
+      </para>
+      </listitem>
+
+     </itemizedlist>
+    </sect3>
+
+    <sect3> 
+     <title>Microsoft Development Tools</title>
+     <itemizedlist>
+  
+      <listitem><command><ulink url="http://download.microsoft.com/download/9/0/f/90f019ac-8243-48d3-91cf-81fc4093ecfd/1830_usa_ddk.iso">Windows Driver Development Kit</ulink> (231 MBytes)</command>
+      </listitem>
+
+      <listitem><command><ulink url="http://www.microsoft.com/express/download/offline.aspx">Visual Studio Express Edition DVD</ulink> (749 MBytes)</command>
+      </listitem>
+
+     </itemizedlist>
+    </sect3>
+
+  </sect2>
+
+
+  <sect2 id="basicsetup">
+   <title>Basic Windows VM Setup</title>
+
+   <para>
+Changing the display to 16bit color depth may conserve resources and is more amenable
+ to most virtual machine software like VM Ware or VirtualBox.
+     <mediaobject>
+      <imageobject><imagedata fileref="img/setup1.png" format="png" /></imageobject>
+     </mediaobject>
+   </para><para><literallayout>
+
+   </literallayout></para>
+
+   <para>
+Disable the screen saver and sleep modes.
+     <mediaobject>
+      <imageobject><imagedata fileref="img/setup2.png" format="png" /></imageobject>
+     </mediaobject>
+   </para><para><literallayout>
+
+   </literallayout></para>
+
+   <para>
+Disable automatic updates. It is recommended that you manage updates offline in the
+ source OS images and not in temporal build host instances.
+     <mediaobject>
+      <imageobject><imagedata fileref="img/setup3.png" format="png" /></imageobject>
+     </mediaobject>
+   </para><para><literallayout>
+
+   </literallayout></para>
+
+   <para>
+The indexing service is not necessary.
+     <mediaobject>
+      <imageobject><imagedata fileref="img/setup4.png" format="png" /></imageobject>
+     </mediaobject>
+   </para><para><literallayout>
+
+   </literallayout></para>
+  </sect2>
+
+
+  <sect2 id="ddkinstall">
+   <title>Install Driver Development Kit</title>
+
+   <para>
+This ISO image has the annoying autorun behavior of launching IE to browse a readme.
+ You will need to "Explore" the CD-ROM rather than double click or open it.
+     <mediaobject>
+      <imageobject><imagedata fileref="img/ddkinst1.png" format="png" /></imageobject>
+     </mediaobject>
+   </para><para><literallayout>
+
+   </literallayout></para>
+
+   <para>
+Run the setup program.
+     <mediaobject>
+      <imageobject><imagedata fileref="img/ddkinst2.png" format="png" /></imageobject>
+     </mediaobject>
+   </para><para><literallayout>
+
+   </literallayout></para>
+
+   <para>
+A graphical installer is provided.
+     <mediaobject>
+      <imageobject><imagedata fileref="img/ddkinst3.png" format="png" /></imageobject>
+     </mediaobject>
+   </para><para><literallayout>
+
+   </literallayout></para>
+
+   <para>
+
+     <mediaobject>
+      <imageobject><imagedata fileref="img/ddkinst4.png" format="png" /></imageobject>
+     </mediaobject>
+   </para><para><literallayout>
+
+   </literallayout></para>
+
+   <para>
+Accept the default location for the install. Do not change the destination.
+     <mediaobject>
+      <imageobject><imagedata fileref="img/ddkinst5.png" format="png" /></imageobject>
+     </mediaobject>
+   </para><para><literallayout>
+
+   </literallayout></para>
+
+   <para>
+Documentation is not necessary.
+     <mediaobject>
+      <imageobject><imagedata fileref="img/ddkinst6.png" format="png" /></imageobject>
+     </mediaobject>
+   </para><para><literallayout>
+
+   </literallayout></para>
+
+   <para>
+The installation will consume about 700 MBytes of disk space.
+     <mediaobject>
+      <imageobject><imagedata fileref="img/ddkinst7.png" format="png" /></imageobject>
+     </mediaobject>
+   </para><para><literallayout>
+
+   </literallayout></para>
+
+   <para>
+
+     <mediaobject>
+      <imageobject><imagedata fileref="img/ddkinst8.png" format="png" /></imageobject>
+     </mediaobject>
+   </para><para><literallayout>
+
+   </literallayout></para>
+
+   <para>
+
+     <mediaobject>
+      <imageobject><imagedata fileref="img/ddkinst9.png" format="png" /></imageobject>
+     </mediaobject>
+   </para><para><literallayout>
+
+   </literallayout></para>
+  </sect2>
+
+
+
+  <sect2 id="installvcpp">
+   <title>Install Visual C++ Express Edition</title>
+
+   <para>
+When the Visual Studio DVD is loaded a setup program should launch automatically
+ via Autorun.
+     <mediaobject>
+      <imageobject><imagedata fileref="img/vsinst1.png" format="png" /></imageobject>
+     </mediaobject>
+   </para><para><literallayout>
+
+   </literallayout></para>
+
+   <para>
+Select Visual C++ 2008 Express Edition for installation.
+     <mediaobject>
+      <imageobject><imagedata fileref="img/vsinst2.png" format="png" /></imageobject>
+     </mediaobject>
+   </para><para><literallayout>
+
+   </literallayout></para>
+
+   <para>
+
+     <mediaobject>
+      <imageobject><imagedata fileref="img/vsinst3.png" format="png" /></imageobject>
+     </mediaobject>
+   </para><para><literallayout>
+
+   </literallayout></para>
+
+   <para>
+Step through the Visual C++ install process.
+     <mediaobject>
+      <imageobject><imagedata fileref="img/vsinst4.png" format="png" /></imageobject>
+     </mediaobject>
+   </para><para><literallayout>
+
+   </literallayout></para>
+
+   <para>
+
+     <mediaobject>
+      <imageobject><imagedata fileref="img/vsinst5.png" format="png" /></imageobject>
+     </mediaobject>
+   </para><para><literallayout>
+
+   </literallayout></para>
+
+   <para>
+The Silverlight Runtime and SQL Server components should not be installed.
+     <mediaobject>
+      <imageobject><imagedata fileref="img/vsinst6.png" format="png" /></imageobject>
+     </mediaobject>
+   </para><para><literallayout>
+
+   </literallayout></para>
+
+   <para>
+Accept the default destination.
+     <mediaobject>
+      <imageobject><imagedata fileref="img/vsinst7.png" format="png" /></imageobject>
+     </mediaobject>
+   </para><para><literallayout>
+
+   </literallayout></para>
+
+   <para>
+
+     <mediaobject>
+      <imageobject><imagedata fileref="img/vsinst8.png" format="png" /></imageobject>
+     </mediaobject>
+   </para><para><literallayout>
+
+   </literallayout></para>
+
+   <para>
+Part way through installation you will need to restart the operating system.
+     <mediaobject>
+      <imageobject><imagedata fileref="img/vsinst9.png" format="png" /></imageobject>
+     </mediaobject>
+   </para><para><literallayout>
+
+   </literallayout></para>
+
+   <para>
+
+     <mediaobject>
+      <imageobject><imagedata fileref="img/vsinst10.png" format="png" /></imageobject>
+     </mediaobject>
+   </para><para><literallayout>
+
+   </literallayout></para>
+
+   <para>
+Once the OS has restarted the installation process will continue.
+     <mediaobject>
+      <imageobject><imagedata fileref="img/vsinst11.png" format="png" /></imageobject>
+     </mediaobject>
+   </para><para><literallayout>
+
+   </literallayout></para>
+
+   <para>
+
+     <mediaobject>
+      <imageobject><imagedata fileref="img/vsinst12.png" format="png" /></imageobject>
+     </mediaobject>
+   </para><para><literallayout>
+
+   </literallayout></para>
+
+   <para>
+It can take quite a few minutes for the install to complete.
+     <mediaobject>
+      <imageobject><imagedata fileref="img/vsinst13.png" format="png" /></imageobject>
+     </mediaobject>
+   </para><para><literallayout>
+
+   </literallayout></para>
+  </sect2>
+
+
+  <sect2 id="vmcheckpoint">
+   <title>SAVE YOUR WINDOWS VIRTUAL DISK IMAGE AT THIS POINT</title>
+<para>Once the necessary software is installed you should shutdown the Windows guest OS
+ and make a backup of the virtual disk image file. You should always build release packages
+ on a clean virtual disk restored from an authenticated backup image.</para>
+  </sect2>
+</sect1>
+
+
+
+<sect1>
+  <title>Running Builds</title>
+
+  <sect2 id="runfullbuild">
+   <title>Launch Full Build</title>
+
+   <para>
+When the build ISO is loaded into a running system with Autorun enabled the build will
+ start automatically.
+     <mediaobject>
+      <imageobject><imagedata fileref="img/bldrun1.png" format="png" /></imageobject>
+     </mediaobject>
+   </para><para><literallayout>
+
+   </literallayout></para>
+
+   <para>
+The install.bat script on the ISO disc can also be invoked directly to start
+ a build.
+     <mediaobject>
+      <imageobject><imagedata fileref="img/bldrun2.png" format="png" /></imageobject>
+     </mediaobject>
+   </para><para><literallayout>
+
+   </literallayout></para>
+
+  </sect2>
+
+  <sect2 id="runpartbuild">
+   <title>Partial and Development Builds</title>
+
+   <para>
+It is often useful to have a build host with most of the common software and toolchain
+ already prepared and only the latest versions of a particular package are desired.
+   </para>
+   <para>
+Select the package(s) you wish to build frequently and launch an ISO build with the
+ appropriate PACKAGE_BUILT=yes in your environment before running install.bat.
+   </para>
+   <para>
+Save this virtual disk image and use it whenever just that software needs
+ building. This method of builds is more suitable for a development buildbot following
+ source commits than the full build of all tools and packages.
+   </para>
+ 
+  </sect2>
+
+  <sect2 id="msysenv">
+   <title>MSYS Development Tools</title>
+
+   <para>
+The build ISO will install a number of MinGW32 and MSYS tools into C:\msys\1.0\. Run the
+ C:\msys\1.0\msys.bat script to start a shell terminal.
+   </para>
+   <para>
+Sources are in the /src/ directory in the msys environment and the buildall.sh script is
+ used to script the process process.
+   </para>
+   <para>
+Run "/src/buildall.sh shell" for a new login shell with all of the PATH and environment
+ prepared for individual package builds and development.
+   </para>
+
+  </sect2>
+</sect1>
+<sect1>
+  <title>Legal Notice</title>
+  <para>
+You may distribute or modify this document according to the terms of the <ulink url="http://www.gnu.org/licenses/fdl-1.2.txt">GNU Free Documentation License Version 1.2 or later</ulink>.
+  </para>
+  <para>
+"<trademark class="registered">Tor</trademark> is a registered trademark of The Tor Project, Inc."
+  </para>
+  <para>
+"<trademark class="registered">VMware</trademark> is a registered trademark of VMware, Inc. in the United States and other jurisdictions."
+  </para>
+  <para>
+"<trademark class="registered">Windows</trademark> is a registered trademark of Microsoft Corporation in the United States and other countries."
+  </para>
+</sect1>
+</article>

Added: torvm/trunk/doc/devel/img/bldrun1.png
===================================================================
(Binary files differ)


Property changes on: torvm/trunk/doc/devel/img/bldrun1.png
___________________________________________________________________
Added: svn:mime-type
   + application/octet-stream

Added: torvm/trunk/doc/devel/img/bldrun2.png
===================================================================
(Binary files differ)


Property changes on: torvm/trunk/doc/devel/img/bldrun2.png
___________________________________________________________________
Added: svn:mime-type
   + application/octet-stream

Added: torvm/trunk/doc/devel/img/ddkinst1.png
===================================================================
(Binary files differ)


Property changes on: torvm/trunk/doc/devel/img/ddkinst1.png
___________________________________________________________________
Added: svn:mime-type
   + application/octet-stream

Added: torvm/trunk/doc/devel/img/ddkinst2.png
===================================================================
(Binary files differ)


Property changes on: torvm/trunk/doc/devel/img/ddkinst2.png
___________________________________________________________________
Added: svn:mime-type
   + application/octet-stream

Added: torvm/trunk/doc/devel/img/ddkinst3.png
===================================================================
(Binary files differ)


Property changes on: torvm/trunk/doc/devel/img/ddkinst3.png
___________________________________________________________________
Added: svn:mime-type
   + application/octet-stream

Added: torvm/trunk/doc/devel/img/ddkinst4.png
===================================================================
(Binary files differ)


Property changes on: torvm/trunk/doc/devel/img/ddkinst4.png
___________________________________________________________________
Added: svn:mime-type
   + application/octet-stream

Added: torvm/trunk/doc/devel/img/ddkinst5.png
===================================================================
(Binary files differ)


Property changes on: torvm/trunk/doc/devel/img/ddkinst5.png
___________________________________________________________________
Added: svn:mime-type
   + application/octet-stream

Added: torvm/trunk/doc/devel/img/ddkinst6.png
===================================================================
(Binary files differ)


Property changes on: torvm/trunk/doc/devel/img/ddkinst6.png
___________________________________________________________________
Added: svn:mime-type
   + application/octet-stream

Added: torvm/trunk/doc/devel/img/ddkinst7.png
===================================================================
(Binary files differ)


Property changes on: torvm/trunk/doc/devel/img/ddkinst7.png
___________________________________________________________________
Added: svn:mime-type
   + application/octet-stream

Added: torvm/trunk/doc/devel/img/ddkinst8.png
===================================================================
(Binary files differ)


Property changes on: torvm/trunk/doc/devel/img/ddkinst8.png
___________________________________________________________________
Added: svn:mime-type
   + application/octet-stream

Added: torvm/trunk/doc/devel/img/ddkinst9.png
===================================================================
(Binary files differ)


Property changes on: torvm/trunk/doc/devel/img/ddkinst9.png
___________________________________________________________________
Added: svn:mime-type
   + application/octet-stream

Added: torvm/trunk/doc/devel/img/setup1.png
===================================================================
(Binary files differ)


Property changes on: torvm/trunk/doc/devel/img/setup1.png
___________________________________________________________________
Added: svn:mime-type
   + application/octet-stream

Added: torvm/trunk/doc/devel/img/setup2.png
===================================================================
(Binary files differ)


Property changes on: torvm/trunk/doc/devel/img/setup2.png
___________________________________________________________________
Added: svn:mime-type
   + application/octet-stream

Added: torvm/trunk/doc/devel/img/setup3.png
===================================================================
(Binary files differ)


Property changes on: torvm/trunk/doc/devel/img/setup3.png
___________________________________________________________________
Added: svn:mime-type
   + application/octet-stream

Added: torvm/trunk/doc/devel/img/setup4.png
===================================================================
(Binary files differ)


Property changes on: torvm/trunk/doc/devel/img/setup4.png
___________________________________________________________________
Added: svn:mime-type
   + application/octet-stream

Added: torvm/trunk/doc/devel/img/vsinst1.png
===================================================================
(Binary files differ)


Property changes on: torvm/trunk/doc/devel/img/vsinst1.png
___________________________________________________________________
Added: svn:mime-type
   + application/octet-stream

Added: torvm/trunk/doc/devel/img/vsinst10.png
===================================================================
(Binary files differ)


Property changes on: torvm/trunk/doc/devel/img/vsinst10.png
___________________________________________________________________
Added: svn:mime-type
   + application/octet-stream

Added: torvm/trunk/doc/devel/img/vsinst11.png
===================================================================
(Binary files differ)


Property changes on: torvm/trunk/doc/devel/img/vsinst11.png
___________________________________________________________________
Added: svn:mime-type
   + application/octet-stream

Added: torvm/trunk/doc/devel/img/vsinst12.png
===================================================================
(Binary files differ)


Property changes on: torvm/trunk/doc/devel/img/vsinst12.png
___________________________________________________________________
Added: svn:mime-type
   + application/octet-stream

Added: torvm/trunk/doc/devel/img/vsinst13.png
===================================================================
(Binary files differ)


Property changes on: torvm/trunk/doc/devel/img/vsinst13.png
___________________________________________________________________
Added: svn:mime-type
   + application/octet-stream

Added: torvm/trunk/doc/devel/img/vsinst2.png
===================================================================
(Binary files differ)


Property changes on: torvm/trunk/doc/devel/img/vsinst2.png
___________________________________________________________________
Added: svn:mime-type
   + application/octet-stream

Added: torvm/trunk/doc/devel/img/vsinst3.png
===================================================================
(Binary files differ)


Property changes on: torvm/trunk/doc/devel/img/vsinst3.png
___________________________________________________________________
Added: svn:mime-type
   + application/octet-stream

Added: torvm/trunk/doc/devel/img/vsinst4.png
===================================================================
(Binary files differ)


Property changes on: torvm/trunk/doc/devel/img/vsinst4.png
___________________________________________________________________
Added: svn:mime-type
   + application/octet-stream

Added: torvm/trunk/doc/devel/img/vsinst5.png
===================================================================
(Binary files differ)


Property changes on: torvm/trunk/doc/devel/img/vsinst5.png
___________________________________________________________________
Added: svn:mime-type
   + application/octet-stream

Added: torvm/trunk/doc/devel/img/vsinst6.png
===================================================================
(Binary files differ)


Property changes on: torvm/trunk/doc/devel/img/vsinst6.png
___________________________________________________________________
Added: svn:mime-type
   + application/octet-stream

Added: torvm/trunk/doc/devel/img/vsinst7.png
===================================================================
(Binary files differ)


Property changes on: torvm/trunk/doc/devel/img/vsinst7.png
___________________________________________________________________
Added: svn:mime-type
   + application/octet-stream

Added: torvm/trunk/doc/devel/img/vsinst8.png
===================================================================
(Binary files differ)


Property changes on: torvm/trunk/doc/devel/img/vsinst8.png
___________________________________________________________________
Added: svn:mime-type
   + application/octet-stream

Added: torvm/trunk/doc/devel/img/vsinst9.png
===================================================================
(Binary files differ)


Property changes on: torvm/trunk/doc/devel/img/vsinst9.png
___________________________________________________________________
Added: svn:mime-type
   + application/octet-stream

More information about the tor-commits mailing list