Note: An open source alternative to this guide is to use the gcc-based MinGW toolset; see the BuildingOnWindowsMinGW page for details.

Note: At the moment, KDE on Windows seems to distribute only 32 bit versions of the libraries. If you are running a 64 bit system, this guide probably won't work.

Thanks to Stefan Löffler and Alain Delmotte for developing this guide.

• Preface
• Required 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
• Q & A

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 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)
• Visual C++ 2008 Express Edition (+SP1)
  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.
  Note: This software is for free (as in "beer", not as in "speech"). To set it up properly first follow the guide from the KDE on Windows project.
• 7-Zip
  for opening tar.gz
  Note: This software is for free (as in "beer", mostly also as in "speech")
• Subversion
  for obtaining the TeXworks source code
  Note: This software is for free (as in "speech")

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 the KDE on Windows project. See their 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 (this includes accented characters, umlauts, etc.; only use ASCII), e.g. C:\KDE
• Install Mode: Package Manager
• Compiler Mode: MSVC 32Bit

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-vc90,
• qt-vc90,
• zlib

Add the KDEDIRS environment variable and adjust your path to include the KDE bin and lib directories according to the 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 select "View all files".

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:

1. Expand the libhunspell project in the solution explorer on the left hand side
2. Right-Click on the hunspell folder under the libhunspell project
3. Choose Add->Existing Item
4. 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 for libhunspell 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 += c:/MinGW514/local/include
	INCLUDEPATH += c:/MinGW514/local/include/poppler
	INCLUDEPATH += c:/MinGW514/local/include/poppler/qt4
	INCLUDEPATH += c:/MinGW514/local/include/hunspell

	LIBS += -Lc:/MinGW514/local/lib
	LIBS += -lpoppler-qt4
	LIBS += -lpoppler
	LIBS += -lfreetype
	LIBS += -lhunspell-1.2
	LIBS += -lz
	LIBS += -lgdi32

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

In addition, unless you are using a poppler installation that includes the xpdf compatibility headers (not provided by default poppler builds, this requires a configure option), you will need to find the line

QMAKE_CXXFLAGS += -DHAVE_POPPLER_XPDF_HEADERS

and comment it out by inserting # at the beginning. The result will be that TeXworks will not automatically locate a poppler-data directory alongside the executable, but will need the poppler data files (for CJK font support) installed in a fixed system location that is dependent on the poppler library build.

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 called 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

Note: When asked whether to save the solution it doesn't matter what you choose.

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 (if they exist) from C:\texworks\texworks-read-only:

• TeXworks.sln
• TeXworks.ncb
• TeXworks.vcproj
• TeXworks.suo

Then run

svn update
qmake -tp vc

from the same directory to update your TeXworks sources and your MSVC project file. Finally open TeXworks.vcproj in MSVC, make sure the Release configuration is selected and build.

Note: When asked whether to save the solution it doesn't matter what you choose.

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.

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-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. 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).
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 guide from the KDE on Windows project.

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 mailing list.