|
Wt
4.11.3
|
Before you start building Wt, you need to ensure you have the proper tools set up to do so. We base the minimum versions of dependencies on a roughly 5-year sliding window and a selection of commonly used operating systems. This means that Wt will be guaranteed to build using:
| Dependency | Configuration flag | Default value | Details |
| OpenSSL | CONNECTOR_HTTP | ON | Used to support the HTTPS protocol in the web client, and the HTTPS protocol in the built-in wthttpd connector. This will only be used of the wthttpd connector is actually build. This is managed by the build flag CONNECTOR_HTTP, which can be ON or OFF. If OpenSSL is not installed in a default location, its prefix needs to be specified with SSL_PREFIX (as a path). |
| Haru Free PDF Library | ENABLE_HARU | ON | Used to provide support for painting to PDF (WPdfImage). This can be managed by using the ENABLE_HARU flag (ON/OFF). If Haru is not installed in a default location, its prefix needs to be specified with HARU_PREFIX (as a path). The library can be configured to link statically with HARU_DYNAMIC (where OFF means static link). Wt relies on an older verion of HARU, below 2.4.0. Something does not quite compile right with higher versions. We may look at including a more recent version (see: #11704). Additionally, there seems to be a rendering bug with higher versions (2.4.0-2.4.3), where floating point values are not correctly rendered (see: #11833). |
| GraphicsMagick | WT_WRASTERIMAGE_IMPLEMENTATION | none | Used for supporting painting to raster images (PNG, GIF, ...) (WRasterImage), which are rendered server-side. This configures in what way images can be rendered in Wt. This is managed by the WT_WRASTERIMAGE_IMPLEMENTATION flag. This flag is a string, and can take the values GraphicsMagick/Direct2D/none. Where GraphicsMagick will require a graphicsmagick installation. If this is not found, it needs to be specified using GM_PREFIX (as a path). Generally speaking GraphicsMagick is a Linux way to handle images, whereas Direct2D is the Windows way. |
| Pango | ENABLED_PANGO | ON | Used for improved font support in the WPdfImage and WRasterImage paint devices. It can be configured by ENABLED_PANGO (ON/OFF). This will allow for more fonts to be used by Wt. |
| PostgreSQL | ENABLE_POSTGRES | ON | Used for the PostgreSQL backend for Wt::Dbo (Dbo::backend::Postgres). This will allow Wt to use PostgreSQL as its Dbo backend. This can be configured using ENABLE_POSTGRES (ON/OFF). If PostgreSQL is not installed in a default location, its prefix needs to be specified with POSTGRES_PREFIX (as a path). |
| Firebird | ENABLE_FIREBIRD | ON | Used for the Firebird backend for Wt::Dbo (Dbo::backend::Firebird). This will allow Wt to use Firebird as its Dbo backend. This can be configured using ENABLE_FIREBIRD (ON/OFF). If Firebird is not installed in a default location, its prefix needs to be specified with FIREBIRD_PREFIX (as a path). By default Wt includes a IBPP implementation (a library for accessing Firebird databases). If one wished to use a custom IBPP implementation, this will require IBPP_SRC_DIRECTORY, which can be found here, together with USE_SYSTEM_IBPP being set to ON. |
| the C API for MySQL (mysqlclient) or the MariaDB connector library | ENABLE_MYSQL | ON | Used for the MySQL/MariaDB backend for Wt::Dbo (Dbo::backend::MySQL). This will allow Wt to use MySQL/MariaDB as its Dbo backend. This can be configured using ENABLE_MYSQL (ON/OFF). If MySQL / MariaDB is not installed in a default location, its prefix needs to be specified with MYSQL_PREFIX (as a path). |
| unixODBC | ENABLE_MSSQLSERVER | ON | Used for the SQL Server backend for Wt::Dbo (Dbo::backend::MSSQLServer). This will allow Wt to use MSSQL as its Dbo backend. This can be configured using ENABLE_MSSQLSERVER (ON/OFF). As the name indicates, this is a Windows backend. But it can also be installed on Linux systems (see: Microsoft's documentation for more information). |
| libunwind | ENABLE_UNWIND | OFF | Used for the saving of backtraces in exceptions (useful for debugging). This can be configured by ENABLE_UNWIND (ON/OFF). If libunwind is not installed in a default location, its prefix needs to be specified with UNWIND_PREFIX (as a path). |
| zlib | HTTP_WITH_ZLIB/td> | Depends | Used for the compression of data over HTTP or using WebSockets. This will only affect the wthttpd connector. This can be configured by HTTP_WITH_ZLIB (ON/OFF). If zlib is not installed in a default location, its prefix needs to be specified with ZLIB_PREFIX (as a path). |
| standalone Asio | WT_ASIO_IMPLEMENTATION/td> | boost | It is possible to use the standalone version of Asio (Asio 1.12.0 or higher) instead of the one in the Boost library. This can be configured by WT_ASIO_IMPLEMENTATION (boost/standalone). If standalone Asio is not installed in a default location, its prefix needs to be specified with ASIO_PREFIX (as a path). |
The library provides two ways for deploying applications: either with the built-in web server (recommended), or using FastCGI (legacy, and soon to be deprecated).
The built-in web server is a simple HTTP and WebSockets server. It supports all of Wt's features, and is simple to setup. This is the recommended way of deploying a Wt application.
FastCGI is also supported if necessary, but it does not support WebSockets.
Each of these two choices correspond to a library, a so-called connector library. Below it is outlined how to configure the build process of Wt to build either or both libraries (libwthttp and libfcgi).
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.
The naming convention of the library puts the d suffix at the end if the library is built in Debug mode, which is regulated through CMAKE_BUILD_TYPE. So for example the normal wt library libwt will be called libwtd.
When using FastCGI, Wt requires a webserver (like Apache or NGINX) which supports the FastCGI protocol.
To build wtfcgi, you need:
The recommended way to build the library is in a separate build directory, for example within the top level of the Wt package:
$ cd wt-x.x.x
$ mkdir build
$ cd build
$ cmake ../
The latter command will try to locate the necessary libraries. If everything is OK, then this should end with something like:
-- Generating done
-- Build files have been written to: /home/{username}/project/wt/build
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 -Dvar=value or using the interactive program:
$ ccmake ../
or
$ cmake-gui ../
The GUI lists all variables that are configurable in Wt's build process.
The section Core Dependencies lists the minimal requirements that are necessary to make Wt build. If you require more functionality, and will also be using optional features, you will need to take the Optional Dependencies into account as well.
The variables specify several build and configuration aspects of Wt, of which the most relevant ones are (there are many more visible in the GUI):
$ make
If you want to speed up compilation, you may want to use multiple threads (e.g. 4):
$ make -j4
$ make install
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).
Fix it by (as user with sufficient permissions):
$ ln -s /your/path/to/lib/libwt.so /usr/lib
$ ln -s /your/path/to/lib/libwtfcgi.so /usr/lib
Deploying an application is different when using FastCGI or the built-in web server (wthttpd).
The examples that come with the library use the connector specified by the build option EXAMPLES_CONNECTOR (see supra).
Some examples need TinyMCE:
$ make -C examples
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. A similar argument goes for icons and the setting of the --docroot variable. Since Wt 3.1.4, you can use the "approot" property to move the additional files that should not be available to browsers outside of the docroot.
$ cd ../examples/foobar # source directory for example foobar
$ ln -s ../../resources . # include standard Wt resource files
$ ../../build/examples/foobar/foobar.wt --docroot . --http-listen 0.0.0.0:8080
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/
You will notice 404 File not Found errors for resources/ files if you are missing the resources files.
These are all the command-line options that are available:
General options:
-h [ --help ] produce help message
-t [ --threads ] arg (=-1) number of threads (-1 indicates that
num_threads from wt_config.xml is to be
used, which defaults to 10)
--servername arg servername (IP address or DNS name)
--docroot arg document root for static files,
optionally followed by a
comma-separated list of paths with
static files (even if they are within a
deployment path), after a ';'
e.g. --docroot=".;/favicon.ico,/resourc
es,/style"
--resources-dir arg path to the Wt resources folder. By
default, Wt will look for its resources
in the resources subfolder of the
docroot (see --docroot). If a file is
not found in that resources folder,
this folder will be checked instead as
a fallback. If this option is omitted,
then Wt will not use a fallback
resources folder.
--approot arg application root for private support
files; if unspecified, the value of the
environment variable $WT_APP_ROOT is
used, or else the current working
directory
--errroot arg root for error pages
--accesslog arg access log file (defaults to stdout),
to disable access logging completely,
use --accesslog=-
--no-compression do not use compression
--deploy-path arg (=/) location for deployment
--session-id-prefix arg prefix for session IDs (overrides
wt_config.xml setting)
-p [ --pid-file ] arg path to pid file (optional)
-c [ --config ] arg location of wt_config.xml; if
unspecified, the value of the
environment variable $WT_CONFIG_XML is
used, or else the built-in default
(/etc/wt/wt_config.xml) is tried, or else
built-in defaults are used
--max-memory-request-size arg (=131072)
threshold for request size (bytes), for
spooling the entire request to disk, to
avoid DoS
--gdb do not shutdown when receiving Ctrl-C
(and let gdb break instead)
--static-cache-control Cache-Control header value for static
files (defaults to max-age=3600)
HTTP/WebSocket server options:
--http-listen arg address/port pair to listen on. If no
port is specified, 80 is used as the
default, e.g. 127.0.0.1:8080 will cause
the server to listen on port 8080 of
127.0.0.1 (localhost). For IPv6, use
square brackets, e.g. [::1]:8080 will
cause the server to listen on port 8080
of [::1] (localhost). This argument can
be repeated, e.g. --http-listen
0.0.0.0:8080 --http-listen [0::0]:8080
will cause the server to listen on port
8080 of all interfaces using IPv4 and
IPv6. You must specify this option or
--https-listen at least once. The older
style --http-address and
--https-address can also be used for
backwards compatibility. If a hostname
is provided instead of an IP address,
the server will listen on all of the
addresses (IPv4 and IPv6) that this
hostname resolves to.
--http-address arg IPv4 (e.g. 0.0.0.0) or IPv6 Address
(e.g. 0::0). You must specify either
--http-listen, --https-listen,
--http-address, or --https-address.
--http-port arg (=80) HTTP port (e.g. 80)
HTTPS/Secure WebSocket server options:
--https-listen arg address/port pair to listen on. If no
port is specified, 80 is used as the
default, e.g. 127.0.0.1:8080 will cause
the server to listen on port 8080 of
127.0.0.1 (localhost). For IPv6, use
square brackets, e.g. [::1]:8080 will
cause the server to listen on port 8080
of [::1] (localhost). This argument can
be repeated, e.g. --https-listen
0.0.0.0:8080 --https-listen [0::0]:8080
will cause the server to listen on port
8080 of all interfaces using IPv4 and
IPv6. If a hostname is provided instead
of an IP address, the server will
listen on all of the addresses (IPv4
and IPv6) that this hostname resolves
to.
--https-address arg IPv4 (e.g. 0.0.0.0) or IPv6 Address
(e.g. 0::0). You must specify either
--http-listen, --https-listen,
--http-address, or --https-address.
--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"
--ssl-enable-v3 Switch on SSLv3 support (not
recommended; disabled by default)
--ssl-client-verification arg (=none) The verification mode for client
certificates.
This is either 'none', 'optional' or
'required'. When 'none', the server
will not request a client certificate.
When 'optional', the server will
request a certificate, but the client
does not have to supply one. With
'required', the connection will be
terminated if the client does not
provide a valid certificate.
--ssl-verify-depth arg (=1) Specifies the maximum length of the
server certificate chain.
--ssl-ca-certificates arg Path to a file containing the
concatenated trusted CA certificates,
which can be used to authenticate the
client. The file should contains a a
number of PEM-encoded certificates.
--ssl-cipherlist arg List of acceptable ciphers for SSL.
This list is passed as-is to the SSL
layer, so see openssl for the proper
syntax. When empty, the default
acceptable cipher list will be used.
Example cipher list string:
"TLSv1+HIGH:!SSLv2"
--ssl-prefer-server-ciphers arg (=0) By default, the client's preference is
used for determining the cipher that is
choosen during a SSL or TLS handshake.
By enabling this option, the server's
preference will be used.
$ make -C examples
The easiest way to deploy the examples is by copying the binary (from your build directory) and the source directory (which contains the images) and the resources/ into the same destination directory somewhere in your Apache server (we no longer generate a ./deploy.sh script that took care of some of this).
$ export DESTINATION=/var/www/localhost/htdocs/wt-examples
$ mkdir -p $DESTINATION/foobar
$ cp -r examples/foobar/* resources/* build/examples/foobar/*.wt $DESTINATION/foobar/
This does however make public also files (such as message resources bundles, data files, etc...) that do not need to be served by your web server. The clean way to deploy your own applications is to use the "approot" property to deploy those files to a directory outside the webserver's doc root.
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.:
FastCgiServer /var/www/localhost/htdocs/wt-examples/composer/composer.wt
1.9.1