#summary Guide to building TeXworks on Windows XP

<wiki:toc max_depth="1" />  

= Preface =

This document describes a procedure for building !TeXworks on Windows XP using the (freely available) Microsoft Visual C++ 2008 Express Edition. It is by no means the only way possible and it doesn't anticipate and tackle all possible problems, either. If you run into any difficulties feel free to ask for help on the [http://tug.org/mailman/listinfo/texworks mailing list].

_Note: This guide is designed for use with the English version on Windows XP. If you use another language the labels and some of the paths will be different._

= Required 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)
  * [http://www.microsoft.com/express/vc/ Visual C++ 2008 Express Edition (+SP1)]<br>for building some required libraries and the program itself. For brevity this application will be referred to as MSVC in the rest of this document.<br>Note: This software is for free (as in "beer", not as in "speech"). To use it after a 30 days trial period you need to register (which is free, too).
  * [http://www.7-zip.org/ 7-Zip]<br>for opening tar.gz<br>Note: This software is for free (as in "beer", mostly also as in "speech")
  * [http://subversion.tigris.org/ Subversion]<br>for obtaining the !TeXworks source code<br>Note: This software is for free (as in "speech")
_Note: You need administrator's privileges to install new software._

= Directory structure =

The following directory layout is used in this guide. 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 =

!TeXworks depends on several external libraries, most notably Qt and Poppler. You can obtain most of the needed dependencies from [http://windows.kde.org/ the KDE on Windows project]. See their [http://techbase.kde.org/Projects/KDE_on_Windows/Installation#Summary_of_Steps summary of steps]
for further information.

Download and run the installer. Choose the following options when asked:
  * Installation Directory: Choose a path *not containing spaces or special characters* (i.e. C:\KDE).
  * Install Mode: Package Manager
  * Compiler Mode: MSVC
_Note: You need administrator's privileges to install some of the packages._

Install the following packages and their dependencies (make sure that you
install both the *"bin" and the "devel"* packages where available):
  * jpeg, 
  * poppler-data, 
  * poppler-msvc, 
  * qt-msvc, 
  * zlib
_Note: Not all available servers provide all necessary packages. If the one you chose doesn't, choose another._

Add the KDEDIRS environment variable and adjust your path to include the KDE bin and lib directories according to the [http://techbase.kde.org/Projects/KDE_on_Windows/Installation#Summary_of_Steps summary of steps required for installation of KDE on Windows]

= Downloading and building Hunspell =

The hunspell library is required for spell checking and is not bundled with KDE on Windows. Hence you have to compile it yourself.

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:/KDE/include/poppler/qt4
	INCLUDEPATH += C:/texworks/hunspell-1.2.8/src/hunspell

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

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 -tp vc
}}}
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 the hunspell dll into 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

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

= Q & A =

I already have the version X of the software/package Y installed. Do I really have to install it again as described in this guide
  You don't necessarily have to. Previous versions or full versions of MSVC shouldn't be a problem. Different versions of the KDE libraries could be a problem, though. This is especially true for different versions of Qt. All the packages of the KDE on Windows project fit together (are compiled by similar compilers and similar configurations, etc.). Mixing versions will most likely cause problems.
  
I really want to install the KDE on Windows packages into a folder containing spaces. Can't it be done?
  Yes, you could try. If everything works well and all settings are correct it should work on most systems. Some of the workarounds presented here won't work, however. So to be on the safe side installing to paths not containing spaces or special characters is recommended. If it doesn't work please try installing the packages to the recommended location before asking for help on the mailing list.

When compiling !TeXworks I get errors similar to WARNING: Unable to generate output for: c:/texworks/texworks/Makefile.Debug (TEMPLATE vcapp)
  This is most likely a problem with your Qt version(s) (see also the previous answer). Not all Qt versions have full support for MSVC. Make sure that the one you use (you shouldn't have more than one, anyway) has a C:\KDE\mkspecs\win32-msvc2008 directory. If it does make sure you have all your environmental variables set correctly. If all this doesn't help you can temporarily override the qmake file generation specification by executing
{{{
qmake -tp vc -spec C:\KDE\mkspecs\win32-msvc2008
}}}

MSVC complains that it can't execute a subprogram or that a subprogram returns an error
  Make sure that you have installed Qt in a path MSVC can find. This includes setting the environmental variables correctly. If you have set the paths in PATH directly (rather than using %KDEDIRS%) make sure your path to Qt doesn't contain spaces or special characters.

When starting !TeXworks it complains about missing or incompatible dlls or simply crashes during start-up
  This can be caused if !TeXworks doesn't find some required dlls at all or finds different versions of the dlls first. This can most notably be caused by MikTeX which includes some Qt dlls. First of all make sure you have your environmental variables set correctly. If this doesn't help copy the following dlls from C:\KDE\bin to C:\texworks\texworks-read-only\release:
  * freetype.dll
  * jpeg62.dll
  * poppler-qt4.dll
  * QtCore4.dll
  * QtGui4.dll
  * QtXml4.dll
  * zlib1.dll

I have a question not answered here. What shall I do?
  Ask the question on the [http://tug.org/mailman/listinfo/texworks mailing list].