== Table of Contents ==

  * Software
  * Directory Structure
  * Obtaining the necessary libraries from KDE on Windows
  * Downloading and building Hunspell
  * Obtaining and building TeXworks
  * Running TeXworks for the first time
  * Updating TeXworks
  * Disclaimer
  
  

== Software ==

  The process described here has been sucessfully implemented using the
  following<software. You may of course use other software, but then the
  described steps may have to be adapted in some places.

  * WinXP (+SP3)

  * Visual C++ 2008 Express Edition (+SP1)
    [http://www.microsoft.com/express/vc/]
        for building libraries and the program. For brevity this application
        will be referred to as MSVC (Microsoft Visual C) in the rest of this
        document.
        Note: This software is for free (although not as in "speech" or "beer").
              To use if after a 30 days trial period you need to register
              (which is free, too).

  * 7-Zip
    [http://www.7-zip.org/]
        for opening tar.gz
        Note: This software is for free (mostly as in "speech" or "beer")

  * Subversion
    [http://subversion.tigris.org/]
        for obtaining the TeXworks source code
        Note: This software is for free (as in "speech" or "beer")

  Note: You need administrator's privileges to install new software.



== Directory structure ==

  I used the following directory layout for building TeXworks and its
  dependencies. If you choose another layout you have to adjust the paths in the
  rest of this guide.
  
    C:\texworks\hunspell-1.2.8\ (hunspell)
    C:\texworks\texworks-read-only\ (TeXworks)



== Obtaining the necessary libraries from KDE on Windows ==

  Download and run the installer found at http://windows.kde.org/
  Note: You need administrator's privileges to install some of the packages

  Install the following packages and their dependencies:
      jpeg, poppler-data, poppler-msvc, qt-msvc, zlib

  Add the KDEDIRS environment variable and adjust your path to include the
  KDE bin directory according to the summary found at
  http://techbase.kde.org/Projects/KDE_on_Windows/Installation#Summary_of_Steps



== Downloading and building Hunspell ==

  Go to http://sourceforge.net/projects/hunspell/ and choose
  Download -> Browse all packages -> Hunspell from the navigation bar at the
  top.

  Download the .tar.gz file (the win32.zip file only contains programs, no
  sources and no libraries).

  At the time of writing, hunspell-1.2.8.tar.gz was the latest version and will
  be used throughout this guide.

  Extract hunspell-1.2.8.tar.gz to C:\texworks\
  
  Open hunspell-1.2.8/src/win_api/Hunspell.sln (the solution needs to be
  converted)

  Two files are missing in the libhunspell project. Follow the next steps to add
  them:
    *) Expand the libhunspell project in the solution explorer on the left hand
       side
    *) Right-Click on the hunspell folder under the libhunspell project
    *) Choose Add->Existing
    *) Choose C:\texworks\hunspell-1.2.8\src\hunspell\replist.*

  Since all other libraries are built in Release mode, hunspell should be built
  in that mode as well. To switch to that mode, choose Configuration Manager
  from the Build menu. In the popup window choose Release_dll as the active
  configuration and close the window.

  Build libhunspell (i.e. by Right-Clicking on libhunspell in the solution
  explorer and choosing "Build")

  There are several warnings but the build should succeed.



== Obtaining and building TeXworks ==

  Run the following command from the command line in the folder C:\texworks
    svn checkout http://texworks.googlecode.com/svn/trunk/ texworks-read-only

  You get a fresh new copy of the latest TeXworks code in the folder
  C:\texworks\texworks-read-only

  In order to build TeXworks you have to modify
  C:\texworks\texworks-read-only\TeXworks.pro to reflect your local
  configuration. Find the lines reading

	INCLUDEPATH += z:/cross-tools/usr/local/include
	INCLUDEPATH += z:/cross-tools/usr/local/include/poppler
	INCLUDEPATH += z:/cross-tools/usr/local/include/poppler/qt4
	INCLUDEPATH += z:/cross-tools/usr/local/include/hunspell

	LIBS += -Lz:/cross-tools/usr/local/lib
	LIBS += -lpoppler-qt4
	LIBS += -lpoppler
	LIBS += -lfreetype
	LIBS += -lhunspell-1.2
	LIBS += -lz
  
  and replace them by

	INCLUDEPATH += C:/Program Files/KDE/include/poppler/qt4
	INCLUDEPATH += C:/texworks/hunspell-1.2.8/src/hunspell

	LIBS += C:/Program Files/KDE/lib/poppler-qt4.lib
	LIBS += C:/Program Files/KDE/lib/poppler.lib
	LIBS += C:/texworks/hunspell-1.2.8/src/win_api/Release_dll/libhunspell/libhunspell.lib
	LIBS += C:/Program Files/KDE/lib/zlib.lib

  Note: This assumes you have an English version of WinXP (otherwise the folder
        Program Files will be named differently) and that you installed the
        KDE libraries in the default location.

  Because the Windows libraries don't seem to support the round() function, add
  the following line to the top of
  C:\texworks\texworks-read-only\src\PDFDocument.cpp

    #define round(x) ((fabs(ceil(x) - (x)) < fabs(floor(x) - (x))) ? ceil(x) : floor(x))

  Then run
    qmake -t vcapp
  on the command line from the C:\texworks\texworks-read-only directory. This
  creates C:\texworks\texworks-read-only\TeXworks.vcproj which can be opened in
  MSVC.

  Choose the Release configuration in the same way as for hunspell (Note: it's
  simply termed Release this time).

  Build TeXworks (i.e. by Right-Clicking on the TeXworks project in the solution
  explorer and choosing "Build"). This creates
  C:\texworks\texworks-read-only\release\TeXworks.exe



== Running TeXworks for the first time ==

  Before you can run TeXworks for the first time you need to copy several DLLs
  in a location where TeXworks can find them:
  * Copy C:\texworks\hunspell-1.2.8\src\win_api\Release_dll\libhunspell\libhunspell.dll
    to C:\texworks\texworks-read-only\release
    
  * Copy the following dlls from C:\Program Files\KDE\bin to
    C:\texworks\texworks-read-only\release:
      jpeg62.dll, QtCore4.dll, QtGui4.dll, QtXml4.dll, zlib1.dll

  Note: You can't currently run TeXworks.exe from within MSVC because it
        complains about memory corruption. Running it normally (from outside
        MSVC) seems to work, though. Investigations of the issue are ongoing.



== Updating TeXworks ==

  Remove the following files from C:\texworks\texworks-read-only
    TeXworks.sln, TeXworks.ncb, TeXworks.vcproj*, TeXworks.suo

  Then run
    svn update
    qmake -t vcapp
  from the same directory to update your TeXworks sources and your MSVC project
  file. Finally open TeXworks.vcproj in MSVC and build.


== Disclaimer ==
  
  This guide is provided as-is in the hope that it's helpful. There is no
  guarantee the described procedure will work on your system. Use at your own
  risk.