#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++ 2005 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.
  * Windows XP (+SP3; Vista should work, too, but wasn't tested yet)
  * [http://www.microsoft.com/express/2005/ Visual C++ 2005 Express Edition (+SP1)] and the [http://www.microsoft.com/express/2005/platformsdk/default.aspx Platform SDK]<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 set it up properly first follow the [http://techbase.kde.org/Getting_Started/Build/KDE4/Windows/MS_Visual_Studio#Visual_Studio_2005_Express_Edition guide from the KDE on Windows project] and then the [http://www.microsoft.com/express/2005/platformsdk/default.aspx additional instructions by Microsoft]. See also the Q&A below.
  * [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

= 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. The full version of MSVC shouldn't be a problem. Other versions will, however (see below). Different versions of the KDE libraries could be a problem as well. 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.

Why do I have to use the (outdated) 2005 edition of MSVC and the Platform SDK?
  As stated above, all the libraries used by a program have to fit together. At the time of writing this guide, all libraries of the KDE on Windows project are built with MSVC 2005. This means they are linked against (=use) the version 8 of the C Runtime (CRT) libraries. These CRT libraries are (amongst other things) responsible for memory allocation, management and for freeing memory. Unfortunately, MSVC 2008 comes with the new version 9 of the CRT libraries which are incompatible with the earlier versions. Hence you can't use MSVC 2008 for linking !TeXworks with the KDE on Windows libraries. F6r additional information about CRT related issues read the [http://www.abisource.com/viewvc/enchant/trunk/msvc/Build.win32.readme?view=markup readme of the enchant library] and the pages referenced therein.<br>Because MSVC 2005 originally was not intended to enable the user to build full-fledged windows application all by itself the Platform SDK is needed in addition to MSVC (ignore the fact that it mentions Windows Server 2003).<br>If you insist on using MSVC 2008 nevertheless you have to build all libraries yourself. This is fairly easily accomplished for Qt (though the process takes a long time) but is tricky and currently not well supported for poppler and its dependecies.

I really want to install the KDE on Windows packages into a folder containing spaces. Can't it be done?
  Yes, you can 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 executing qmake I get errors similar to `WARNING: Unable to generate output for: c:/texworks/texworks/Makefile.Debug (TEMPLATE vcapp)`. What's wrong?
  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-msvc2005 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-msvc2005
}}}

MSVC complains that it can't execute a subprogram or that a subprogram returns an error. Why?
  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.

MSVC complains about linking errors/unresolved references. Why?
  Make sure that you have chosen the Release configuration during compilation (KDE on Windows doesn't provide debugging libraries). If you change the configuration you need choose *rebuild* for the whole project (just hitting build again isn't enough as the old stuff is still lurking in some files).<br>If you get errors regarding unresolved references make sure you followed this guide completely (setting all paths properly). Also make sure that you followed the [http://techbase.kde.org/Getting_Started/Build/KDE4/Windows/MS_Visual_Studio#Visual_Studio_2005_Express_Edition guide from the KDE on Windows project] and the [http://www.microsoft.com/express/2005/platformsdk/default.aspx steps for setting up the Platform SDK], in particular step 4.

When starting !TeXworks it complains about missing or incompatible dlls or simply crashes during start-up. What's wrong?
  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].