Project

General

Profile

Installing Wt on MS Windows » History » Version 54

Wim Dumon, 02/12/2016 01:58 PM

1 15 Pieter Libin
h1. Installing Wt on MS Windows
2 1 Pieter Libin
3
{{toc}}
4
5 16 Wim Dumon
This HOWTO assumes you have a clean Windows system and want to use Wt 2.1 or newer series. 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.
6 1 Pieter Libin
7 38 Charles Brockman
Unlike Linux distributions, Windows has no easy package managers for developers. To avoid compiling dependencies for half a day before you can use Wt, we strongly reduced the minimal dependencies that Wt requires. Since Wt 2.1, Boost and CMake are the only required dependencies. We will explain two approaches to set up your environment: the quick method, using binary packages, and the thorough method, in which you compile more dependencies, but which will also result in a Wt that supports compression, SSL, etc.
8 1 Pieter Libin
9 49 Wim Dumon
These instructions are valid for all 2.1 and newer versions of Wt.
10 1 Pieter Libin
11 41 Charles Brockman
h2. Setting Up Your Compiler 
12 1 Pieter Libin
13 38 Charles Brockman
You need Microsoft Visual Studio 2005 or newer, Professional or 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.
14 1 Pieter Libin
15 16 Wim Dumon
For more information about the compiler, see [[Installing MSVC]].
16 1 Pieter Libin
17 34 Wim Dumon
Note for MSVC 2010 SP1 users: "FIX: Visual C++ compilers are removed when you upgrade Visual Studio 2010 Professional or Visual Studio 2010 Express to Visual Studio 2010 SP1 if Windows SDK v7.1 is installed":http://support.microsoft.com/?kbid=2519277
18
19 44 Wim Dumon
h2. The Easy Method
20
21 54 Wim Dumon
Wt binary releases are now available for MSVS compilers. They can be downloaded from "the github Wt release area":https://github.com/kdeforche/wt/releases (old versions of Wt are still available on "the Wt Sourceforge Download area":https://sourceforge.net/projects/witty/files/wt/ )
22 44 Wim Dumon
23
These downloads contains Wt and related dependencies (boost, openssl, libharu, libpng, zlib, ...) and all compiled examples with appropriate bat files to run them.
24
25 54 Wim Dumon
To compile your own application using these binary releases, set the following properties in your MSVS project:
26
* In C/C++ -> General, Additional Include Directories: c:/location/of/wt-x.y.z/include
27 51 Wim Dumon
* In C/C++ -> Preprocessor, ensure that WIN32 is defined. Also define HPDF_DLL, which will allow you to generate pdf files.
28 45 Wim Dumon
* In Linker->General, Additional Library Directories: c:/location/of/wt-3.3.1/lib
29 46 Wim Dumon
* Go to Linker->Input. In the Additional Dependencies, fill out the Wt libraries you want to link to. At the topleft of the dialog, check the active Configuration. If it's Debug, link to wtd.lib, wthttpd.lib (and optionally wtdbod.lib, wtdbobackendXXXd.lib, ...). If it's release, link to wt.lib, wthttp.lib (and optionally wtdbo.lib, wtdbobackendXXX.lib). Notice that the debug libraries have a 'd' suffix. Be carefull. You need different libraries depending on the Release/Debug configuration, since it's not possible to mix different versions of the MSVC runtime libraries in one application.
30 45 Wim Dumon
31 47 Wim Dumon
If you want to run your fresh application, set these options:
32 1 Pieter Libin
* In the Debugging tab, set Command Arguments to @--docroot . --http-address 0.0.0.0 --http-port 8080@
33 54 Wim Dumon
* In the Debugging tab, set Environment to PATH=c:/location/of/wt-x.y.z/bin
34 45 Wim Dumon
35 44 Wim Dumon
These installers are new, so if you encounter any problems please report them in the "Wt Forums":http://redmine.webtoolkit.eu/projects/wt/boards/2
36
37 13 Pieter Libin
h2. The Quick Method 
38 1 Pieter Libin
39 54 Wim Dumon
The quick method installs Wt without any optional components (without HTTP compression, HTTPS, server-side graphics rendering, postgres, mysql, ...)
40 1 Pieter Libin
41 13 Pieter Libin
h3. Download Dependencies 
42 1 Pieter Libin
43 52 Wim Dumon
* Install Boost. Either download binaries, or compile your own:
44 43 Wim Dumon
Do not use boost version 1.54 on windows (bug in boost asio). Do not use boost 1.46 or newer with Wt < 3.1.11 on Windows (bug https://svn.boost.org/trac/boost/ticket/6320). Boost > 1.36 is required.
45 52 Wim Dumon
> * To compile Boost yourself, download the Boost sources from boost.org. Use the following command:
46 36 Wim Dumon
<pre>
47
bootstrap
48 52 Wim Dumon
bjam --layout=versioned variant=debug threading=multi link=static runtime-link=shared install
49
bjam --layout=versioned variant=release threading=multi link=static runtime-link=shared install
50 36 Wim Dumon
</pre>
51 53 Wim Dumon
> * Since boost 1.54, boost.org provides "binary boost packages for Windows":http://www.boost.org/users/download/ (note: untested for use with Wt)
52 54 Wim Dumon
* Download the "cmake 3":http://www.cmake.org/ (cmake > 2.4.6 required) Windows Installer. Run the installer to install CMake.
53 35 Wim Dumon
* Download Wt from the "download page":http://www.webtoolkit.eu/wt/download. Unzip it somehwere (c:/projects/witty/wt-3.x.x).
54 1 Pieter Libin
55
h3. Configuring Wt 
56
57 39 Charles Brockman
* Start the CMake GUI from the Start->CMake menu
58
* At the top of the window that opens, fill in or browse to the source and binary directories:
59
** Where is the source code: c:\projects\witty\wt-3.x.x
60
** Where to build the binaries: c:\projects\witty\wt-3.x.x\build
61 13 Pieter Libin
* Click Configure
62 54 Wim Dumon
* Select the right version of Visual Studio
63 1 Pieter Libin
64 39 Charles Brockman
You will probably get errors about Boost not being found. That is normal, as you did not yet tell where the library is located. Set the BOOST_PREFIX variable to match your configuration. For example:
65 54 Wim Dumon
* BOOST_PREFIX = c:/boost
66 18 Anonymous
67
Another error you might encounter in CMake is "The C compiler "cl" is not able to compile a simple test program." This means that your Visual Studio won't find 'cmd' as it isn't configured correctly.
68
69 39 Charles Brockman
What you must do is change the MSVC options (Tools menu > Options > Project and Solutions > VC++ Directories) to ensure that
70 18 Anonymous
71 1 Pieter Libin
*    $(SystemRoot)
72 18 Anonymous
*    $(SystemRoot)\System32
73 1 Pieter Libin
*    $(SystemRoot)\System32\wbem
74 18 Anonymous
75 39 Charles Brockman
are specified BEFORE $(PATH).
76 18 Anonymous
77 50 Wim Dumon
If cmake complains about a DLL not being found, just click 'ok' and ignore the error. This has no effect on the generated project files.
78
79 1 Pieter Libin
Press 'Configure' again. A few messages about the FCGI and wthttpd connector may pop up; just click Ok. A few new configuration fields (in red) will have popped up; leave them unchanged and press 'Configure' once more. If all went well, you have now no red fields left and the configuration is complete. Press Generate (in cmake <2.8, this button is called 'Ok') and your MSVC solution files will be generated.
80 35 Wim Dumon
81 1 Pieter Libin
h3. Compiling Wt 
82 13 Pieter Libin
83 1 Pieter Libin
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.
84 39 Charles Brockman
85 1 Pieter Libin
h3. Installing Wt 
86
87 41 Charles Brockman
After compilation, open the Solution Explorer and right-click on the 'INSTALL' project. Select 'build'. This will copy the Wt header files and libraries to c:/Program Files/WT.
88 1 Pieter Libin
89 13 Pieter Libin
h2. Optional Components 
90 38 Charles Brockman
91 1 Pieter Libin
This involves installing SSL, zlib and some other components. After installation as described here, rerun CMake. These instructions are valid for Wt > 2.1.0.
92 13 Pieter Libin
93 1 Pieter Libin
h3. Preparations 
94 13 Pieter Libin
95 1 Pieter Libin
In order to avoid setting paths to small libraries separately, we create a repository where we store them all. CMake will find this repository without assistance if you call it 'c:\libraries'.
96 39 Charles Brockman
<pre>
97 13 Pieter Libin
mkdir c:\libraries
98 38 Charles Brockman
mkdir c:\libraries\lib
99 1 Pieter Libin
mkdir c:\libraries\include
100
</pre>
101
102
h3. Download and Build zlib 
103
104
Zlib is an optional dependency of Wt, which can be controlled by the CMake flag HTTP_WITH_ZLIB. With zlib, Wt compresses all http traffic by default, saving bandwidth.
105
106
* Download the zlib library from the "zlib home page":http://www.zlib.net/ Select your preferred format (tar.gz, tar.bz2 or zip) and download location. 
107
* In Microsoft Visual Studio, open zlib-1.2.x\contrib\vstudio\vc8\zlibvc.sln.
108
* Select solution 'Debug', architecture 'Win32' (in the toolbar)
109
* Right-click on project 'zlibstat', select Properties. In 'Configuration Properties'->'C/C++'->'Code Generation'->'Runtime Libraries' and set it to 'Multi-threaded Debug DLL (/MDd)'. Close the properties window.
110
* Do the same with project 'zlibvc'
111
* Right-click on project 'zlibstat', and select 'Build' to build it.
112
* Select solution 'Release', architecture 'Win32' 
113
* Right-click on project 'zlibstat', select Properties. In 'Configuration Properties'->'C/C++'->'Code Generation'->'Runtime Libraries' and set it to 'Multi-threaded DLL (/MD)'. Close the properties window.
114
* Do the same with project 'zlibvc'* Right-click on project 'zlibstat', and select 'Build' to build it.
115
116
The results are now located in the x86 directory. Copy them into our central repository location, renaming the debug library in the process:
117
<pre>
118
cp contrib\vstudio\vc8\x86\ZlibStatDebug\zlibstat.lib c:\libraries\lib\zlibstatd.lib
119
cp contrib\vstudio\vc8\x86\ZlibStatRelease\zlibstat.lib c:\libraries\lib\
120
</pre>
121
We also need zlib.h and zconf.h header files.
122
<pre>
123
cp zlib.h zconf.h c:\libraries\include
124
</pre>
125
126
h3. OpenSSL 
127
128
You need OpenSSL if you want to use Wt to support https mode. Grab a pre-compiled binary from http://www.openssl.org/related/binaries.html, install it in the default path (c:\OpenSSL) and Wt's CMake files will find and use OpenSSL. (Verify that HTTP_WITH_SSL is enabled.)
129
130
h3. GraphicsMagick
131
132
The generic build instructions for GraphicsMagick are found here: http://www.graphicsmagick.org/INSTALL-windows.html#installing-from-source-code
133
134
In order for GraphicsMagick to work with your version of MSVC, it is strongly recommended to build it from the sources. Follow the instructions on the GraphicsMagick site:
135
* Run @VisualMagick/configure/configure.exe@ to create a .sln file
136
* Make sure to select the default 'Dynamic Multi-threaded DLL runtimes' and 'Use X11 stubs to prevent use of X windows'
137
* Open @VisualMagick/VisualStaticMT.sln@ in MSVC and press F7. Make sure you select the 'Release' or 'Debug' build as appropriate. For me, the UTIL_IMDisplay project fails to compile, which is unimportant.
138
139
While configuring Wt, point GM_PREFIX to the toplevel directory of GraphicsMagick (i.e. the one containing subdirectories VisualMagick and magick). Press Configure, and CMake should find the header files and compiled binaries.
140
141
Important: when executing a binary linked to a Wt library that uses GraphicsMagick, the GraphicsMagick DLLs must be found by Windows. This means that they should be in c:/windows/system32, or in the current working directory, or that you should add the VisualMagick/bin directory to your path. Otherwise your application will complain that it cannot find the required DLLs to start up.
142 39 Charles Brockman
143 13 Pieter Libin
In order to render fonts, verify that your imagemagick fonts are correctly configured. For example, on my computer I had to remove the include for type-ghostscript.mgk in the VisualMagick/bin/type.mgk file to have any fonts rendered at all.
144 41 Charles Brockman
145
h2. Running the Examples 
146
147
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
148
149
<pre>
150
--http-address=0.0.0.0 --http-port=8080 --deploy-path=/hello --docroot=.
151
</pre>
152
153
Wt builds static versions of all libraries by default and links against static Boost libraries by default. If you would choose to build dynamic libraries in the future (see remarks at the bottom of this page), 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:
154
<pre>
155
PATH=c:/libraries/lib;c:/Boost/lib;<path to wt.dll>;<path to wthttp.dll>
156
</pre>
157
158
Right-click on the example project you want to run and select 'Set as Startup Project'. Press F5 (Run). This will start the httpd server listening on all local interfaces, on port 8080, and you may browse the example at http://127.0.0.1:8080/hello
159
160
Examples that need extra files to run should be executed from their source directory in order to find their dependency files (icons, CSS files, etc). Watch for 404 errors in Wt's output. To do so, set the 'Working directory' for the example to wt-2.x.x/examples/ExampleName. Some examples (e.g. the Wt home page) need the 'resources' directory to work correctly. Copy the wt-2.x.x/resources to the example's source directory to solve this problem. Other examples (such as the Charts example) may require the installation of ExtJs. See the Wt reference manual for more information on how to obtain and install ExtJs.
161
162
These are all the command-line options that are available (run the wt application with --help to see the newer options available in your version):
163
<pre>
164
General options:
165
  -h [ --help ]              produce help message
166
  -t [ --threads ] arg (=10) number of threads
167
  --docroot arg              document root for static files
168
  --no-compression           do not compress dynamic text/html and text/plain 
169
                             responses
170
  --deploy-path arg (=/)     location for deployment
171
172
HTTP server options:
173
  --http-address arg    IPv4 (e.g. 0.0.0.0) or IPv6 Address (e.g. 0::0)
174
  --http-port arg (=80) HTTP port (e.g. 80)
175
176
HTTPS server options:
177
  --https-address arg     IPv4 (e.g. 0.0.0.0) or IPv6 Address (e.g. 0::0)
178
  --https-port arg (=443) HTTPS port (e.g. 443)
179
  --ssl-certificate arg   SSL server certificate chain file
180
                          e.g. "/etc/ssl/certs/vsign1.pem"
181
  --ssl-private-key arg   SSL server private key file
182
                          e.g. "/etc/ssl/private/company.pem"
183
  --ssl-tmp-dh arg        File for temporary Diffie-Hellman parameters
184
                          e.g. "/etc/ssl/dh512.pem"
185
</pre>
186 27 Wim Dumon
187 13 Pieter Libin
h2. Important Remarks 
188 1 Pieter Libin
189 38 Charles Brockman
By default, Wt will build static libraries that are statically linked against Boost. While this is convenient for quick deployment (the example binaries do not require DLLs to run, so you do not have to set their PATHs correctly), many people prefer to use DLLs, not in the least because your Wt applications will link much faster.
190 1 Pieter Libin
191 38 Charles Brockman
Two CMake options control how Wt is built, and what kind of Boost libraries it uses:
192
* BOOST_DYNAMIC: set to true to build against Boost DLLs. Set to false to link to static Boost libraries.
193 13 Pieter Libin
* SHARED_LIBS: set to true to build a Wt DLL, set to false to build a static Wt library.
194 1 Pieter Libin
195 38 Charles Brockman
If you double-checked the library directories but still get build errors such as "cannot open file 'libboost_signals-vc90-mt-gd-1_35.lib'", you probably did not install or build the static Boost files, while the BOOST_DYNAMIC option is set to false. Similarly, when the error indicates that boost_signals-vc90-mt-gd-1_35.lib is not found, you probably haven't installed or built the Boost DLLs, while BOOST_DYNAMIC is set to true.
196 10 Pieter Libin
197 38 Charles Brockman
Note that when you build a static Wt library (SHARED_LIBS is false), you will get these Boost-related linker errors only when you compile the examples.
198 25 Wim Dumon
199
h2. Support for Microsoft IIS
200
201
Wt works well with Microsoft IIS as ISAPI extensions. See the [[ISAPI on Microsoft IIS]] wiki for more information on how to deploy Wt in IIS.