Project

General

Profile

Frequently Asked Questions » History » Version 31

Wim Dumon, 03/31/2014 01:12 PM

1 9 Pieter Libin
h1. Frequently Asked Questions
2
3
{{toc}}
4
5 5 Pieter Libin
h2. Building and deployment
6 1 Pieter Libin
7 17 Koen Deforche
h3. Q: I built Wt and the examples, but many examples don't display correctly
8 1 Pieter Libin
9 17 Koen Deforche
If you are running the built example from within the build directory, then the examples will not find their resources bundles (.xml) files and the resources (CSS, images) will not be where they are to be expected.
10 3 Pieter Libin
11 17 Koen Deforche
The examples are designed that you can run them without much hassle from the source directory.
12 3 Pieter Libin
13 17 Koen Deforche
For example, to run composer, you should do the following:
14
<pre>
15
$ cd wt/examples/composer   # source directory for composer example
16
$ ln -s ../../resources .   # link the resources folder
17
$ ../../build/examples/composer/composer.wt --docroot . --http-address 0.0.0.0 --http-port 8080
18
</pre>
19 3 Pieter Libin
20 29 Wim Dumon
Applications that have explicit approot and/or docroot directories (e.g. widgetgallery), must be started with the appropriate --approot and --docroot parameters:
21
<pre>
22
$ cd wt/examples/widgetgallery # source directory for composer example
23
$ ln -s ../../../resources docroot   # link the resources in the docroot folder
24
$ ../../build/examples/widgetgallery/widgetgallery.wt --docroot docroot --approot approot --http-address 0.0.0.0 --http-port 8080
25
</pre>
26
27 5 Pieter Libin
h3. Q: How do I build my newly written "Hello World!" application?
28 1 Pieter Libin
29 21 Koen Deforche
Wt itself, and the examples, use "CMake":http://www.cmake.org, but that is entirely a personal choice. You can use any build environment, like qmake, where
30 3 Pieter Libin
you:
31 12 Koen Deforche
32 11 Koen Deforche
* specify the library directory (Wt defaults to installing in @/usr/local/lib@)
33 12 Koen Deforche
* specify the link libraries:
34 1 Pieter Libin
** @-lwt@ and @-lwthttp@ or @-lwtfcgi@ (for release build)
35 13 Koen Deforche
** @-lwtd@ and @-lwthttpd@ or @-lwtfcgid@ (for debug build)
36 1 Pieter Libin
* specify the include directory (Wt defaults to installing in @/usr/local/include@)
37 3 Pieter Libin
38 21 Koen Deforche
Unlike Qt, there is no need for special features such as moc for starting a Wt project.
39 15 Koen Deforche
40 21 Koen Deforche
If you decide to use CMake, and have installed Wt in its default location (within @/usr/local@), this @CMakeLists.txt@ file should do it:
41 1 Pieter Libin
42
<pre>
43 30 Wim Dumon
INCLUDE_DIRECTORIES(/usr/local/wt/include)
44
#LINK_DIRECTORIES(/usr/local/lib)
45
46 3 Pieter Libin
ADD_EXECUTABLE(myprog.wt
47
MyProg1.C
48
OtherFile.C
49
AndEvenMoreCode.C
50
)
51
52
# For FastCGI deployment:
53
TARGET_LINK_LIBRARIES(myprog.wt
54
wtfcgi wt someotherlib
55
)
56
57 1 Pieter Libin
# Or, for built-in httpd deployment:
58 3 Pieter Libin
# TARGET_LINK_LIBRARIES(myprog.wt
59
#   wthttp wt someotherlib
60 1 Pieter Libin
# )
61 15 Koen Deforche
62 3 Pieter Libin
</pre>
63
64 24 Pieter Libin
When you did not install the Wt libraries in /usr/local/lib/, you will need to use the LINK_DIRECTORIES command to inform CMake about the location of the Wt libraries. Make sure to use this command before the ADD_EXECUTABLE and/or ADD_LIBRARY command.
65
66 21 Koen Deforche
The examples use a @CMakeLists.txt@ which is customized for using the current build of Wt, and not that one that is already installed some place (with make install). Therefore, it is not really the recommended way to bootstrap your own Wt project. Also, the @./deploy@ scripts are very primitive, and are a bit specific for the examples. Deploying is nothing more than copying the files to some directory in your html root.
67 3 Pieter Libin
68
*The other methods are:*
69 5 Pieter Libin
70 21 Koen Deforche
To handle many sourcefiles, dependencies... you need a makefile. Obviously, the way Wt is designed, you should have quickly many files for the many classes that will compose your app. Wt uses CMake:http://cmake.org to make makefiles and that is probably a good choice. Just like many others, I switched to CMake (from hand-written makefiles) because of Wt and I am pretty happy with it.
71
72
@make@ should produce the executable. At this point, you probably need to move the output of make to a directory available to your webserver; in practice you therefore need a script that is going to deploy the file. When you name the app, be sure the extension is recognized by the webserver.  Also, you may need to kill active processes of your app and maybe copy the css and some other files (icons...) to the directory available to the webserver.
73 15 Koen Deforche
In the end, I bundled all that in a deploy file located in the build directory (the one that is usually created for CMake). After I have have finished changing the source files, I just type @./deploy@ on the command line and I can refresh my web page.
74 21 Koen Deforche
75 1 Pieter Libin
<pre>
76 3 Pieter Libin
make
77
target_app=app.wt
78
target_path=httpdocs
79
ps -A | grep app.wt | awk '{print $1}' | xargs kill
80
rm -f "~/${target_path}/${target_app}"
81
cp "${target_app}" ~/${target_path}/
82
cp ../app.css  ~/${target_path}/
83
</pre>
84 1 Pieter Libin
85
*OR*
86
87 5 Pieter Libin
You can use install command instead of cp, more or less like this:
88 3 Pieter Libin
<pre>
89
install -m 0755 astariand.wt /var/www/game
90 1 Pieter Libin
install -m 0644 messages.xml /var/www/game
91
install -m 0644 astariand.css /var/www/game
92
install -m 0644 login.php /var/www/game
93
install -m 0644 includes.php /var/www/game
94
install -m 0755 -d /var/www/game/media
95
install -m 0755 -d /var/www/game/media/icons
96
install -m 0644 media/icons/* /var/www/game/media/icons
97
install -m 0755 -d /var/www/game/media/images
98
install -m 0644 media/images/* /var/www/game/media/images
99
</pre>
100
101 21 Koen Deforche
Using install has two advantages. First, it allows you to set permissions on the fly (just as user and group, but I don't use this). Second, with
102
dedicated process session management you don't need to kill all processes beforehand - old connections will keep using the old binary and new
103
connections will use the new one, until all old connections "die from natural reasons".
104 1 Pieter Libin
105
h3. Q: My browser shows a window with a message like 'Wt internal error: ReferenceError: Ext is not defined, code: undefined, description: undefined'. How do I resolve it?
106
107
Check your log for 404 messages regarding ExtJs. Download Ext 2.0.1 or 2.0.2 from the ExtJs homepage and install it as described "here":http://www.webtoolkit.eu/wt/doc/reference/html/group__ext.html. ExtJs 2.0.2 is available for download "here":http://yogurtearl.com/ext-2.0.2.zip.
108
109
You will receive similar error messages when you use a WTextEdit and TinyMCE is not properly deployed. Download TinyMCE from the "TinyMCE homepage":http://tinymce.moxiecode.com/.
110
111
ExtJS and TinyMCE need to be available in the document root of your web server. By default, Wt expects ext-related files to be found in 'ext/' (relative to your application deployment location), and TinyMCE in 'resources/tiny_mce/'.
112
113
For example (Wt 2.2.1), to run the widgetgallery example (which needs both ExtJS and TinyMCE) from within its source directory, you need the following organisation of auxiliary files:
114
115
<pre>
116
 $ pwd
117
 /home/.../wt/examples/widgetgallery
118
 $ ls ext/
119
 ext-all.js  ext-base.js  resources
120
 $ ls resources/
121
 collapse.gif      items-ok.gif     nav-minus.gif              nav-plus-line-middle.gif  sort-arrow-down.gif  tab_l.gif
122
 expand.gif        line-last.gif    nav-minus-line-last.gif    orbited.js                sort-arrow-none.gif  tab_r.gif
123
 iframe.js         line-middle.gif  nav-minus-line-middle.gif  orbited_LICENSE.txt       sort-arrow-up.gif    tiny_mce
124
 items.gif         line-trunk.gif   nav-plus.gif               slider-thumb-h.gif        stripes              tv-line-last.gif
125
 items-not-ok.gif  loading.png      nav-plus-line-last.gif     slider-thumb-v.gif        tab_b.gif
126
 $ ls resources/tiny_mce/
127
 langs  license.txt  plugins  themes  tiny_mce.js  tiny_mce.js.gz  tiny_mce_popup.js  tiny_mce_src.js  utils
128
</pre>
129
130
and then you can run the example using the following command line:
131
132
<pre>
133
 $ ../../build/examples/widgetgallery/widgetgallery.wt --http-address=0.0.0.0 --http-port=8080 --docroot .
134
</pre>
135
136
h3. Q: My browser shows an empty window and I am disappointed now.
137 17 Koen Deforche
138 21 Koen Deforche
See the previous question.
139 17 Koen Deforche
140 25 Peter Mortensen
h3. Q: How does Wt organize sessions in processes and threads?
141 17 Koen Deforche
142 21 Koen Deforche
Wt makes a distinction in the conceptual organization (which is reflected in the API of WApplication) and the way the application is actually deployed.
143 17 Koen Deforche
144 21 Koen Deforche
_Conceptually_, every user session is completely isolated from each other. For each new session, Wt calls the function that is supplied to WRun(), to create a WApplication object for that session. As a programmer, you should program for the general case where different WApplication objects are in different processes, and thus if you wish to communicate between different session, you have the following options: (in increasing order of flexibility traded for convenience):
145 17 Koen Deforche
* A database to which every session connects.
146
* A dedicated server daemon, with socket based communication.
147
* A combination of both, with possible peer-to-peer communication between different sessions.
148
149 21 Koen Deforche
_Physically_, Wt offers several choices for deployment, each of them with different trade-offs. If an application sticks strictly to the previous rules, you can freely change between different deployment options at deployment time.
150 17 Koen Deforche
151
The options that are available are:
152
* Dedicated-process mode: mapping one session to one process. Advantages are:
153
** Kernel-level isolation between processes (security and reliability!).
154
** Kernel-based sharing of read-only memory segments (simply UNIX feature).
155 21 Koen Deforche
** Development friendly: a new session uses the latest deployed binary, and valgrind may be used to debug one particular session, by modifying the URL request.
156 17 Koen Deforche
157
* Shared-process mode: mapping multiple sessions in a fixed number of processes. Advantages are:
158
** No process and stack overhead per session.
159 20 Koen Deforche
160 21 Koen Deforche
Wt is capable of using multi-threading to improve performance for both situations. Threads are used for simultaneous handling of requests. Even in dedicated-process mode, several requests may be handled simultaneously, for example concurrent streaming of different @WResource@'s. The multi-threading feature however is more important for shared-process mode, for handling concurrent requests for different sessions. In the latter case, however, the number of threads must not
161 17 Koen Deforche
equal the number of active sessions: threads are reused after every request is handled.
162
163 21 Koen Deforche
The shared-process mode has the notable disadvantage, inherent to C++, that memory corruption may occur and can take down all sessions. It is however well suited for 'open' applications on the Internet (and the Wt homepage and all examples are deployed this way). If you design a restricted access application, or possibly a security sensitive application, or deploy the application on a private intranet, the dedicated process mode may be more suitable.
164 17 Koen Deforche
165 25 Peter Mortensen
h3. Q: How does it compare to Java servlets?
166 17 Koen Deforche
167 21 Koen Deforche
Differences with Java Servlets are mostly due to the Java Virtual Machine. Java has the benefit of automating pointer manipulation, and therefore eliminating unwanted interference between different sessions because of pointer bugs. On the other hand, because of the high costs (both run-time start up as well as memory usage) associated with a Java Virtual Machine instance, Java cannot afford kernel-level isolation between different Java sessions. If not programmed properly, two sessions can still interfere through for example the use of class static variables. Unfortunately, some servlet based frameworks, like the often-used struts framework, actually encourage sharing of for example form objects between different sessions for run-time efficiency reasons, making session cross talk readily an issue.
168 17 Koen Deforche
169 21 Koen Deforche
Similarities between Wt and Java Servlets are the use of a thread pool to serve concurrent requests, and the abstraction of actual deployment details from the API, allowing easy scalability.
170 3 Pieter Libin
171 1 Pieter Libin
Note: you should consider using "JWt":http://www.webtoolkit.eu/jwt if you would like to develop in Java.
172 5 Pieter Libin
173 1 Pieter Libin
h2. API
174 15 Koen Deforche
175 25 Peter Mortensen
h3. Q: How do I deal with look and layout? Does Wt support CSS?
176 15 Koen Deforche
177 31 Wim Dumon
Wt provides you with options for layout.
178 1 Pieter Libin
179 31 Wim Dumon
180
181 1 Pieter Libin
* You can use CSS for layout, and CSS may be either specified in CSS style sheets, or manipulated programmatorically. Tomasz Mazurek contributed [[Using CSS|a tutorial]] about it.
182 31 Wim Dumon
183
* You can use WTemplate for composing Wt widgets together in a layout. Within the templates, you can use CSS, but also Twitter Bootstrap for layouting.
184
185
* Wt's Twitter Bootstrap theme is a themable theme. Wt's widgets support rendering in bootstrap style, so if you compose your own program with WTemplate in bootstrap's style, you can benefit from Bootstrap and the Bootstrap themes you can find online (+ most design agencies know how to design a Bootstrap theme).
186 15 Koen Deforche
187 3 Pieter Libin
* You can use Wt's layout managers (e.g. @WBoxLayout@, @WGridLayout@, @WBorderLayout@). These have the advantage over CSS-based layouts that you also have control over vertical layout, but require JavaScript to work properly.
188 5 Pieter Libin
189 25 Peter Mortensen
h3. Q: How do I pass an additional argument from a signal to a slot?
190 3 Pieter Libin
191
Frequently, you may want to connect many different signals to a single slot, and identify the original sender in the slot.
192
193 1 Pieter Libin
For example:
194 5 Pieter Libin
195 3 Pieter Libin
<pre>
196 1 Pieter Libin
 void Test::createWidgets()
197 3 Pieter Libin
 {
198
   // create text1, text2, text3 widgets
199
 
200 28 Wim Dumon
   text1->clicked.connect(this, &Test::onClick);
201
   text2->clicked.connect(this, &Test::onClick);
202
   text3->clicked.connect(this, &Test::onClick);
203 3 Pieter Libin
 }
204
 
205
 void Test::onClick()
206
 {
207
   // How to know which widget?
208
 }
209 5 Pieter Libin
</pre>
210 1 Pieter Libin
211 28 Wim Dumon
Boost's boost.bind allows you to pass a 'generalized' function pointer where some (or all) of its arguments can be bound to a value of your choice:
212 3 Pieter Libin
<pre>
213
 void Test::createWidgets()
214 1 Pieter Libin
 {
215 28 Wim Dumon
   // Actually you can write onClick to accept any kind of argument
216
   // (int, enum, object pointer, ...). We chose to pass the sending widget
217
   // here.
218
   text1->clicked().connect(boost::bind(this, &Test::onClick, text1));
219
   text2->clicked().connect(boost::bind(this, &Test::onClick, text2));
220
   text3->clicked().connect(boost::bind(this, &Test::onClick, text3));
221 1 Pieter Libin
 }
222
 
223
 void Test::onClick(Wt::WText* source)
224
 {
225
   // source is where it is coming from
226 3 Pieter Libin
   // ...
227 5 Pieter Libin
 }
228 1 Pieter Libin
</pre>
229
230 28 Wim Dumon
231
The solution based on "WSignalMapper":http://www.webtoolkit.eu/wt/doc/reference/html/classWt_1_1WSignalMapper.html is considered deprecated.
232
233 3 Pieter Libin
234 1 Pieter Libin
h3. Q: How do I update my application window from another thread, or from a socket notifier?
235 18 Joe VanAndel
236
A:
237
See the documentation for Wt::WApplication::enableUpdates().
238
239
h2. Security
240 5 Pieter Libin
241 1 Pieter Libin
242 5 Pieter Libin
h3. Q: Building web applications in a low-level language like C? Have you never heard of buffer overruns??
243 3 Pieter Libin
244 1 Pieter Libin
We are well aware of the hostile environment that is the Internet. We believe that Wt provides some unique benefits compared to other solutions to handle the most common attacks:
245 3 Pieter Libin
246 15 Koen Deforche
* *Cross-Site scripting attacks (XSS)*: an attacker forces the display of some script by letting the application render it to the browser of a victim that is also using the web application.
247
** Unlike other web technologies, Wt does not require any effort from the programmer to avoid XSS attacks. Instead, any 'rich' XHTML text that needs to be displayed (for example in a @WText@ using @XHTMLFormatting@) is filtered by a built-in XML parser for any potentially malicious tags or attributes (which is anything that may execute some JavaScript code). Unlike other (low-level) frameworks, Wt provide this protection because there is no raw 'print' command. Instead, Wt generates all HTML/JavaScript from widgets and therefore it knows that rich text should only be "passive" rich text and not contain any "active" content.
248 20 Koen Deforche
249 15 Koen Deforche
* *Cross-site request forgery attacks (CSRF)*: an attacker tricks a user into sending a request to a trusted website passing its credentials in a cookie.
250 3 Pieter Libin
** This kind of attack is eliminated since Wt uses a secure random number generator for the session ID (on platforms that provide this kernel-level service, such as Linux and Win32 platforms), and even when using cookies for session tracking, the session ID is always sent within the request as well, and verified within Wt (since Wt 2.2.0).
251 8 Pieter Libin
252
* Attacks against the *application logic*: an attacker issues a request to some page or service that is only accessible after authorization. 
253
** Wt protects the application logic because all incoming requests are interpreted in one central, well-tested routine. The request is parsed and only _*exposed event signals*_ may be triggered. Exposed event signals are attached to widgets that are currently rendered on the screen. For example, a button click on a button that is currently shown on the screen. In this way, the logic of the application (such as for example: you need to first log
254 5 Pieter Libin
in, and then only you may request for a payment) is automatically validated: only code in slots connected to exposed signals can be invoked by the user.
255 8 Pieter Libin
256 15 Koen Deforche
* *Session cross-talk*: sensitive data from one session spills in another session because of a programming error, where data is shared.
257 8 Pieter Libin
** Wt is the only solution which may eliminate any cross-talk between sessions by deploying each session in a dedicated process, and thus using kernel-level protection (Dedicated Process mode of deployment). In the case of a bug, data from other sessions cannot be accessed and this is guaranteed by the kernel. This feature is especially valuable in sensitive areas such as financial transactions.
258 3 Pieter Libin
** In other web application frameworks, such as Python/PHP/Java solutions, cross-talk between sessions is always a risk since sessions run within the same process for performance reasons since virtual machines and byte interpreters take their time to load. Cross-talk can be the consequence of a programming mistake where data structures are shared between sessions. In fact, many popular Java servlet-based frameworks encourage sharing of data structures, again for performance reasons, to avoid (expensive) object creation. For example, in struts _*form beans*_ should be shared, and be reused by reinitialization rather than reconstruction.
259 8 Pieter Libin
260 15 Koen Deforche
* *Buffer over-runs*: A low-level C programming mistake is abused by an attacker to execute arbitrary code.
261 16 Koen Deforche
** While it is true that C applications may suffer this problem, this is no longer a valid concern for modern C++ code. The main source of these programming mistakes was string manipulation in C, relying on careful memory management of the string buffers. In C++, *std::string* avoids this issues entirely by automated memory management and buffer sizing. Furthermore, Wt is developed using the highest standards for code clarity (so we believe), and is thoroughly checked for memory-related problems by running it through memory checking tools such as valgrind.
262 3 Pieter Libin
263
All these attacks (except for the last one) are commonly exploited against current-day web applications which are vulnerable by the simple fact that too many web-related details are in the hands and responsibility of the developer. In contrast, Wt actively helps in avoiding programming mistakes which may lead to these exploits.
264
265 25 Peter Mortensen
h3. Q: How do I use the built-in HTTPS server in @wthttpd@?
266 3 Pieter Libin
267
You will need a private server key that is signed by a certificate authority, and a temporary file containing random Diffie-Hellman parameters. If you are simply experimenting with the feature, then you can create and sign a key yourself, or use the one that comes with the OpenSSL distribution (server.pem, which has the password 'test'). The file with Diffie-Hellman parameters can be created using the command:
268
269
<pre>
270 1 Pieter Libin
$ openssl dhparam -check -text -5 512 -out dh512.pem
271
</pre>
272
273
Then start Wt using:
274
275
<pre>
276
$ ./app.wt --https-address=0.0.0.0 --ssl-certificate=server.pem --ssl-private-key=server.pem --ssl-tmp-dh=dh512.pem
277
</pre>
278
279
Provide the password at the prompt.
280 5 Pieter Libin
281 22 Wim Dumon
To generate your own self-signed certificate:
282
<pre>
283
# This sequence is found all over the internet:
284
openssl genrsa -des3 -out server.key 1024
285
openssl req -new -key server.key -out server.csr
286
cp server.key server.key.org
287
openssl rsa -in server.key.org -out server.key # removes the passphrase
288
openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt
289
# The PEM file is a combination of what is above:
290
cat server.crt server.key server.crt > server.pem
291
</pre>
292 5 Pieter Libin
293
h2. Trouble shooting
294
295 1 Pieter Libin
296 27 Wim Dumon
h3. Q: My application crashes, and my apache error log shows no information.
297 1 Pieter Libin
298 21 Koen Deforche
There is a known problem with mod_fcgid: STDERR (including everything printed to std::cerr) is not saved to the apache error log.
299 16 Koen Deforche
300 1 Pieter Libin
Wt uses STDERR by default for all error reporting. You can use a different log file in your @wt_config.xml@ file (<log-file>).
301
302 23 Ray Charlesson
You may also consider using mod_fastcgi or the built-in web server (wthttpd) during development. The latter is especially convenient for development as it allows you to start from within a debugger, or diagnose memory-related problems with valgrind.