Wt

h1. Installing Wt on MS Windows

{{toc}}

This HOWTO assumes you have a clean Windows system and want to use Wt. We start with the download of the compiler and system libraries. We continue to explain where the dependency libraries can be found and how they are installed. Then the configuration of Wt is covered, and finally we build Wt and run the examples.

<b>Wt version 2.1.x has its own installation instructions: [[Installing Wt 2.1 on MS Windows]]</b>

Unlike Linux distributions, Windows has no easy package manager for developers. This means that you will have to compile everything from scratch, and that there is very little similarity between the packages with respect to how and where they are installed. This HOWTO proposes a directory structure that will work with Wt's cmake configuration. We have made a significant progress toward minimizing the amount of obligatory dependency projects, but there are still a few left.

These instructions have been tested both on Windows XP and Windows Vista.

<b>You are looking at an old HOWTO, applicable only for older versions of Wt (< 2.0.5). See [[Installing Wt 2.1 on MS Windows]] for the latest information.</b>

h2. Setting up your compiler 

You need either Microsoft Visual Studio 2005 Professional or Microsoft Visual Studio 2005 Express Edition (C++). The difference is that the former is payware, whereas the latter is a free reduced version of MSVC. The good news is that the Express Edition is perfect to compile Wt.

For more information about the compiler, see [[Installing MSVC 2005]].

h2. Installing Wt's dependencies 

h3. Preparations 

In order to avoid to set paths to small library separately, we create a repository where we store them all. CMake will find this repository without intervention if you call it 'c:\libraries'.

<pre>

mkdir c:\libraries

mkdir c:\libraries\lib

mkdir c:\libraries\include

</pre>

h3. Boost 

The developers have mainly used boost 1.33.1 up till now. The boost.org recently released version 1.34 of their libraries, which are slightly different to set up. Boost does not include the asio library, so it has to be installed separately. You can choose to install either 1.33.1 or 1.34, or both, even with the same prefix.

h4. Version 1.33.1 

* Download the boost sources (boost_1_33_1.tar.bz2) from http://www.boost.org/

* Download the binary of bjam (boost-jam-3.1.14-1-ntx86.zip)

* Extract the boost sources, e.g. in c:\tmp\boostbuild

* Extract bjam and copy it in the boost directory (c:\tmp\boostbuild\boost_1_33_1)

* Start a Visual Studio 2005 Command Prompt (Start->All Programs->Visual Studio 2005->Visual Studio Tools)

* Change to your boost build directory (cd \tmp\boostbuild\boost_1_33_1)

* Run bjam:

<pre>

bjam "-sTOOLS=vc-8_0" "--prefix=c:\libraries" install

</pre>

* Ignore messages about python and others

h4. Version 1.34.1 

* Download the boost sources (boost_1_34_1.tar.bz2) from http://www.boost.org/

* Download the binary of bjam (boost-jam-3.1.14-1-ntx86.zip)

* Extract the boost sources, e.g. in c:/tmp/boostbuild

* Extract bjam and copy it in the boost directory (c:\tmp\boostbuild\boost_1_34_1)

* Start a Visual Studio 2005 Command Prompt (Start->All Programs->Visual Studio 2005->Visual Studio Tools)

* Change to your boost build directory (cd \tmp\boostbuild\boost_1_34_1)

* Run bjam:

<pre>

bjam --toolset=msvc-8.0 --prefix=c:\libraries install

</pre>

h4. Boost asio 

* Download boost asio from http://asio.sourceforge.net/ (boost_asio_0_3_7.tar.bz2; newer versions will not work without extra modifications)

* Untar boost asio inside boost's include directory (c:\libraries\include\boost)

* Apply this "patch":http://sources.gentoo.org/viewcvs.py/gentoo-x86/dev-cpp/asio/files/asio-0.3.7-recursive_init.patch?rev=1.1&view=markup to boost asio:

<pre>

--- ./include/asio/ssl/detail/openssl_init.hpp.orig	2006-11-15 00:10:08.000000000 +0100

+++ ./include/asio/ssl/detail/openssl_init.hpp	2006-11-15 00:10:38.000000000 +0100

@@ -45,13 +45,13 @@

       {

         ::SSL_library_init();

         ::SSL_load_error_strings();        

+        ::OpenSSL_add_ssl_algorithms();

         mutexes_.resize(::CRYPTO_num_locks());

         for (size_t i = 0; i < mutexes_.size(); ++i)

           mutexes_[i].reset(new asio::detail::mutex);

         ::CRYPTO_set_locking_callback(&do_init::openssl_locking_func);

-        ::OpenSSL_add_ssl_algorithms();

       }

     }

</pre>

Boost asio is a headerfile-only library, so no compilation is required.

h3. MXML 

Wt now includes MXML as part of the download and build process. MXML is no longer a dependency; it is mentioned here only because it is required for older versions of Wt.

Newer versions of Wt use mxml instead of Xerces. Mxml is much smaller and depends on much less than Xerces, so for our purpose that is good news.

* Download "Mini-XML":http://www.minixml.org/ (mxml-2.3.tar.gz)

* Apply the following patch to avoid compile errors:

<pre>

--- mxml-2.3-orig/mxml-string.c 2007-04-18 15:14:10.000000000 +0200

+++ mxml-2.3/mxml-string.c      2007-07-07 14:59:58.697309500 +0200

@@ -30,6 +30,7 @@

 #include "config.h"

+char *_mxml_vstrdupf(const char *format, va_list ap);

 #ifdef HAVE_SNPRINTF

 /*

--- mxml-2.3-orig/vcnet/config.h        2007-04-18 15:14:10.000000000 +0200

+++ mxml-2.3/vcnet/config.h     2007-07-07 18:01:18.009809500 +0200

@@ -48,9 +48,9 @@

 /*

  * Do we have the snprintf() and vsnprintf() functions?

  */

-

-/*#undef HAVE_SNPRINTF */

-/*#undef HAVE_VSNPRINTF */

+#define snprintf _snprintf

+#define HAVE_SNPRINTF 1

+#define HAVE_VSNPRINTF 1

 /*

</pre>

* Open the solution mxml-2.3\vcnet\mxml.sln. Convert the solution to a 2005 solution by clicking 'Finish'.

* Build both the debug and the release version of the library: First select 'Debug' as Solution Configuration and right-click on mxml and select Build; then select 'Release' as Solution configuration and right-click on mxml and select Build again.

Two static libraries have been built now: mxml.lib and mxmld.lib. We copy them, together with the header files, to our central repository directory:

<pre>

cp mxml.h c:\libraries\include

cp *.lib c:\libraries\lib

</pre>

h3. zlib 

* Download "zlib":http://www.zlib.net/zlib-1.2.3.tar.gz

* Open zlib-1.2.3\contrib\vstudio\vc8\zlibvc.sln

* Select solution 'Debug', architecture 'Win32' and press F7 (Build all)

* Select solution 'Release', architecture 'Win32' and press F7 (Build all)

Results are now located in the x86 directory. We can use either the dynamic libraries (ZlibDll*) or the static libraries (ZlibStat*). We assume the static libraries (they're less hassle at runtime). Copy them into our central repository location, renaming the debug library in the process:

<pre>

cp contrib\vstudio\vc8\x86\ZlibStatDebug\zlibstat.lib c:\libraries\lib\zlibstatd.lib

cp contrib\vstudio\vc8\x86\ZlibStatRelease\zlibstat.lib c:\libraries\lib\

</pre>

We also need zlib.h and zconf.h header files.

<pre>

cp zlib.h zconf.h c:\libraries\include

</pre>

h3. cmake 

* Download the Win32 Installer (cmake-2.4.6-win32-x86.exe) from http://www.cmake.org/

* Run the installer

CMake is now ready for use.

h3. OpenSSL (optional) 

OpenSSL is used by the wthttpd connector to support encrypted links over http (SSL). The compilation of the OpenSSL library will be covered later.

h3. libgd (optional) 

h3. libmysql (optional) 

h3. libmysql++ (optional) 

h3. cygwin (optional) 

I prefer to use cygwin (http://www.cygwin.com/) for cvs access over ssh. Other options are available, and you don't even need CVS access unless you want the bleeding edge Wt version.

h2. Download Wt 

The following versions of Wt are known to compile according to the instructions of this HOWTO:

* None

Feel free to report success here if we forgot to add our latest version to this list.

h2. Configuring Wt 

* Start cmake from the Start->CMake menu

* Where the source code is: c:\projects\witty\wt

* Where to build the binaries: c:\projects\witty\wt\build (or whatever)

* Click Configure

* Select Visual Studio 8 2005

You will probably get errors about OpenSSL not being found. Don't panic, we can disable it.

* Find HTTP_WITH_SSL and set it to 'OFF'

Press 'Configure' again. A few messages about the FCGI and wthttpd connector may pop up; click Ok. If all went well, you have now no red fields left and the configuration is complete. Press 'Ok' and your MSVC solution files will be generated.

h2. Compiling Wt 

Open the WT.sln solution in the 'Where to build the binaries' directory of the previous step. Press F7, or select the projects you want to build manually. You should not get any compile or link errors.

h2. Running the examples 

In the MSVC IDE Right-click on the example project you want to run, and select 'Properties'. In Configuration Properties->Debugging, set the Command Arguments to

<pre>

--http-address=0.0.0.0 --http-port=8080 --deploy-path=/hello --docroot=.

</pre>

The easiest way to locate the dependency dlls, is to append their location to the PATH variable. In order to do so, change the Environment field to contain a PATH directive:

<pre>

PATH=c:/libraries/lib;c:/Boost/lib;<path to wt.dll>;<path to wthttp.dll>

</pre>

Right-click on the example project you want to run and select 'Set as Startup Project'. Press F5 (Run). This will start a httpd server listening on all local interfaces, on port 8080, and you may browse the example at http://127.0.0.1:8080/hello

These are all the command-line options that are available:

<pre>

General options:

<pre>

  -h [ --help ]              produce help message

  -t [ --threads ] arg (=10) number of threads

  --docroot arg              document root for static files

  --no-compression           do not compress dynamic text/html and text/plain 

                             responses

  --deploy-path arg (=/)     location for deployment

</pre>

HTTP server options:

<pre>

  --http-address arg    IPv4 (e.g. 0.0.0.0) or IPv6 Address (e.g. 0::0)

  --http-port arg (=80) HTTP port (e.g. 80)

</pre>

HTTPS server options:

<pre>

  --https-address arg     IPv4 (e.g. 0.0.0.0) or IPv6 Address (e.g. 0::0)

  --https-port arg (=443) HTTPS port (e.g. 443)

  --ssl-certificate arg   SSL server certificate chain file

                          e.g. "/etc/ssl/certs/vsign1.pem"

  --ssl-private-key arg   SSL server private key file

                          e.g. "/etc/ssl/private/company.pem"

  --ssl-tmp-dh arg        File for temporary Diffie-Hellman parameters

                          e.g. "/etc/ssl/dh512.pem"

</pre>

</pre>