1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
</head>
<title>Wt Installation</title>
<body>
<h1>Wt Installation instructions on Unix-like systems</h1>
This page lists the instructions for building and installing Wt 3.0.0.
It is organized in 3 sections:
<ul>
<li>Requirements</li>
<li>Building and installing the library</li>
<li>Trying the examples (or your own Wt application)</li>
</ul>
<a name="requirements"></a><h2>Requirements</h2>
<p>
The library provides two ways for deploying applications: either using
the FastCGI protocol, in conjunction with a webserver (like apache),
or using a built-in web server (wthttpd). You only need one of these,
but you can have both of them.</p>
<p>
The built-in web server is more convenient during development and is
easier to setup.</p>
<p>
The FastCGI based solution provides more flexibility for deployment of
the application. The built-in web server runs all sessions in a single
process, while the FastCGI based solution allows different deployment
schemes including dedicated processes per sessions.</p>
<p>
Each of these two choices correspond to a library, a
so-called <i>connectory</i> library. Below it is outlined how to
configure the build process of Wt to build either or both libraries
(libwthttp and libfcgi).</p>
<p>
Thus, to build a Wt library with built-in web server you need to
link against libwt and libwthttp. To build a Wt library which acts as
a FastCGI process, you need to link against libwt and libfcgi.
</p>
<h3>1 Wt requirements</h3>
<ul>
<li>Compiler: gcc-3.3.4 or higher, or gcc-4.1.x or higher, or other
Ansi C++ compiler that can deal with boost-like C++ code.</li>
<li>CMake cross-platform build system (www.cmake.org):
<div>Preferably CMake 2.6, which comes with a usable script for
finding boost libraries, but CMake 2.4 is still supported using
Wt's own boost find script.
</div>
</li>
<li>C++ boost library (version 1.36 or higher), preferably with thread
support enabled. You can verify you have a thread-enabled boost
installation by locating the libboost_thread library. Thread support
is not essential: Wt functionality is not affected except for exotic
things like server push and reentrant event loops. Most importantly,
even without thread support Wt can handle multiple concurrent
sessions.</li>
</ul>
<h4>1a Using FastCGI</h4>
<p>When using FastCGI, Wt requires a webserver (like apache, lighttpd or
nginx) which supports the FastCGI protocol.</p>
<p>Given that Apache is still the most popular webserver, below are
the requirements for apache, for other web servers the list is
similar:</p>
<ul>
<li>FCGI library, including C++ bindings (libfcgi++)</li>
<li>Fastcgi or mod_fcgi plugin for Apache.</li>
</ul>
<h4>1b Using wthttpd</h4>
When using the built-in webserver, two more libraries may be installed
to enable optional features (you can also build without them), but
otherwise no extra dependencies are required.
<ul>
<li>(optionally) libz, for compression over HTTP.</li>
<li>(optionally) openssl, for supporting HTTPS.</li>
</ul>
<h3>2 Additional and optional requirements for some of the examples</h3>
<ul>
<li>libgd2 (style, mandelbrot)</li>
<li>libmysql++-2.x (hangman)</li>
</ul>
<hr />
<a name="build"></a><h2>Building and installing the Wt library</h2>
<h4>1. Create a build directory</h4>
<p>The recommended way to build the library is in a seperate build
directory, for example within the top-level of the Wt package:</p>
<pre>
$ cd wt-x.xx
$ mkdir build
$ cd build
</pre>
<h4>2. Configure the library</h4>
<pre>
$ cmake ../
</pre>
<p>The latter command will try to locate the necessary libraries. If everything
is OK, then this should end with something like:
<pre>
-- Generating done
-- Build files have been written to: /home/kdforc0/project/wt/build
</pre></p>
<p>To build a multi-threaded version of Wt, which uses multiple
threads for handling concurrent requests, you need a thread-enabled
boost library. By default, CMake 2.6 will only search for a
thread-enabled boost installation, while CMake 2.4 will fall-back to a
non-multithreaded boost library, reporting:
<pre>
...
-- Looking for pthread_create in pthread - found
** Disabling multi threading.
...
</pre></p>
<p>Most linux distributions provide multi-threaded boost libraries by
default now.</p>
<p>If CMake fails, because it cannot resolve all dependencies, then you
may help CMake by setting some variables to help CMake locate the libraries.
This may be done on the command-line using -D<i>var</i>=<i>value</i> or
using the interactive program:
<pre>
$ ccmake .
</pre>
<p>Variables that you may set to configure Wt's built-in boost finding
method:</p>
<dl>
<dt><strong>BOOST_COMPILER</strong></dt>
<dd>The boost compiler signature. For a library
libboost_regex-gcc41-mt-1_37.so, this is 'gcc41'</dd>
<dt><strong>BOOST_VERSION</strong></dt>
<dd>The boost compiler signature. For a library
libboost_regex-gcc41-mt-1_37.so, this is '1_37'</dd>
<dt><strong>BOOST_DIR</strong></dt>
<dd>The boost installation directory. This is the directory where lib/
and include/ are located for your boost installation.</dd>
</dl>
Other variables specify several build and configuration aspects of Wt, of which
the most relevant ones are:
<dl>
<dt><strong>CMAKE_INSTALL_PREFIX</strong></dt>
<dd>Installation prefix for the library and include files)</dd>
<dt><strong>CONFIGDIR</strong></dt>
<dd>Path for configuration files (default is /etc/wt/)</dd>
<dt><strong>CONNECTOR_FCGI</strong></dt>
<dd>Build the FastCGI connector (libwtfcgi) ?</dd>
<dt><strong>CONNECTOR_HTTP</strong></dt>
<dd>Build the stand-alone httpd connector (libwthttp) ?</dd>
<dt><strong>EXAMPLES_CONNECTOR</strong></dt>
<dd>Which connector library to use for the examples? (wthttp or wtfcgi)</dd>
<dt><strong>MULTI_THREADED</strong></dt>
<dd>Build a multi-threaded wthttpd? While on by default, and
recommended, you may want to disable this for example if you suspect
threading problems. Note that recursive event loops (most notably when
using Dialog::exec()) are not possible without thread support.</dd>
</dl>
The following variables apply to the FastCGI connector:
<dl>
<dt><strong>RUNDIR</strong></dt>
<dd>Default location for Wt runtime session management (can be overridden in the Configuration file)</dd>
<dt><strong>WEBUSER</strong></dt>
<dd>Webserver username: used to assign permissions to RUNDIR</dd>
<dt><strong>WEBGROUP</strong></dt>
<dd>Webserver groupname: used to assign permissions to RUNDIR</dd>
<dt><strong>DEPLOYROOT</strong></dt>
<dd>Path to deploy examples into -- if you want that.</dd>
</dl>
The following variables apply to the wthttpd connector:
<dl>
<dt><strong>WTHTTP_CONFIGURATION</strong></dt>
<dd>Location of the wthttpd configuration file (default is /etc/wt/wthttpd)</dd>
<dt><strong>HTTP_WITH_SSL</strong></dt>
<dd>Compile with support for SSL, for secure HTTP (HTTPS). This requires an OpenSSL library.</dd>
<dt><strong>HTTP_WITH_ZLIB</strong></dt>
<dd>Compile with support for compression over HTTP. This requires the
libz library.</dd>
</dl>
To change any entry, use [Enter]. To save and quit, do [c] followed by [g].
</p>
<h4>3. Build the library</h4>
<pre>
$ make
</pre>
<h4>4. Install the library (as user with sufficient permissions):</h4>
<pre>
$ make install
</pre>
<h4>5. Get your LD_LIBRARY_PATH ok, if needed (mostly for FastCGI).</h4>
<p>
If you did not install Wt in a directory (CMAKE_INSTALL_PREFIX) included
in the default linker dynamic library search path, then the web server will
not be able to start Wt programs (such as the examples).</p>
<p>
Fix it by (as user with sufficient permissions):
<pre>
$ ln -s /your/path/to/lib/libwt.so /usr/lib
$ ln -s /your/path/to/lib/libwtfcgi.so /usr/lib
</pre>
</p>
<hr />
<a name="examples"></a><h2>Trying the examples (or your own Wt application)</h2>
<p>Deploying an application is different when using FastCGI or the
built-in web server (wthttpd).</p>
<p>The examples that come with the library use the connector specified
by the build option EXAMPLES_CONNECTOR (see supra).</p>
<p>Some examples need third-party JavaScript libraries (ExtJS or TinyMCE).
<ul>
<li>Download ExtJS
from <a href="http://yogurtearl.com/ext-2.0.2.zip">http://yogurtearl.com/ext-2.0.2.zip</a>,
and install it according to these instructions:
<a href="http://www.webtoolkit.eu/wt/doc/reference/html/group__ext.html">http://www.webtoolkit.eu/wt/doc/reference/html/group__ext.html</a>
</li>
<li>Download TinyMCE
from <a href="http://tinymce.moxiecode.com/">http://tinymce.moxiecode.com/</a>
and install its <tt>tiny_mce</tt> folder into the resources/ folder.
</li>
</ul>
You will notice 404 File not Found errors for <tt>ext/</tt> or
<tt>resources/tiny_mce/</tt> if you are missing these JavaScript
libraries.
</p>
<a name="examples-fastcgi"></a></a><h3>A. Using FastCGI and apache</h3>
<h4>1. Build the examples</h4>
<pre>
$ make -C examples
</pre>
<h4>2. Deploy the example <i>X</i></h4>
<pre>
$ cd examples/<i>X</i>
$ ./deploy.sh
</pre>
<h4>3. Configure Apache</h4>
<p>
Treat the example as a mod_fastcgi application, by adding a line to
20_mod_fastcgi.conf in your Apache configuration modules.d/ directory, e.g.:
</p>
<pre>
FastCgiServer /var/www/localhost/htdocs/wt-examples/composer/composer.wt
</pre>
<h4>4. Restart apache</h4>
<a name="examples-wthttpd"></a><h3>B. Using wthttpd</h3>
<h4>1. Build the examples</h4>
<pre>
$ make -C examples
</pre>
<h4>2. Run the example <i>X</i></h4>
<p>
Most examples use additional files, such as message resource bundles,
which are not indicated with absolute path names. Therefore the
working directory should be the source directory for the example
(unless you use the ./deploy.sh script to deploy everything in a
dedicated deployment directory). A similar argument goes for icons and
the setting of the --docroot variable.
</p>
<pre>
$ cd ../examples/<i>X</i> # source directory for example <i>X</i>
$ ln -s ../../resources . # include standard Wt resource files
$ ../../build/examples/<i>X</i>/<i>X</i>.wt --docroot . --http-address 0.0.0.0 --http-port 8080
</pre>
<p>
This will start a httpd server listening on all local interfaces, on
port 8080, and you may browse the example at <a
href="http://127.0.0.1:8080/">http://127.0.0.1:8080/</a></p>
<p>
To make sure the web server has all auxiliary files (like images, CSS
style sheets, and perhaps other things) in place for the web
application, you could use the ./deploy.sh script to copy everything
into a directory (see the cmake DEPLOYROOT variable)</p>
<p>
You will notice 404 File not Found errors for resources/ files if you are
missing the resources files.
</p>
<p>
These are all the command-line options that are available:
<pre>
General options:
-h [ --help ] produce help message
-t [ --threads ] arg (=10) number of threads
--servername arg (=vierwerf) servername (IP address or DNS name)
--docroot arg document root for static files
--errroot arg root for error pages
--accesslog arg access log file (defaults to stdout)
--no-compression do not compress dynamic text/html and text/plain
responses
--deploy-path arg (=/) location for deployment
--session-id-prefix arg prefix for session-id's (overrides wt_config.xml
setting)
-p [ --pid-file ] arg path to pid file (optional)
-c [ --config ] arg location of wt_config.xml. If unspecified,
WT_CONFIG_XML is searched in the environment, if
it does not exist then the compiled-in default
(/etc/wt/wt_config.xml) is tried. If the default
does not exist, we revert to default values for
all parameters.
HTTP server options:
--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)
HTTPS server options:
--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>
</p>
</body>
</html>
|
