INSTALL

                          Wt::Ruby Installation instructions

   Based in the Wt install instructions included in Wt-2.2.3

   This page lists the instructions for building and installing Wt::Ruby 0.9.1.
   It is organized in 3 sections:
     * Requirements
     * Building and installing the library
     * Trying the examples (or your own Wt::Ruby application)

Requirements
   * Either Wt 2.2.3 (or higher), or Wt 2.99.2 or higher
   * Ruby 1.8.x or Ruby 1.9.1 
   * cmake 2.6.x 
   * Boost 1.35 recommended (used to test Wt::Ruby), but 1.35 or greater 
   should work

   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.

   The built-in web server is more convenient during development and is
   easier to setup.

   The FastCGI based solution provides more flexibility for deployment of
   the application. The built-in web server a single session in a single
   process, while the FastCGI based solution allows dedicated processes per
   sessions.

   Each of these two choices correspond to a Ruby extension. By requiring 'wt'
   in your code, and setting the WT_ENV environment variable to either
   'development' or 'production' you can pull in one of the 'wthttp' or 'wtfcgi'
   extensions. The first is for use in development from the command line, and
   the second for production   with an Apache2 web server and FastGCI.

  1 Unix-like

     * 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.
     * CMake cross-platform build system (www.cmake.org): cmake-2.4+.
     * Wt 2.2.3 or higher built with the '-DCONNECTOR_FCGI=YES' AND
       '-DMULTI_THREADED=NO'
     * Wt 2.99.2 or higher will work too.                                                                                      

    1a Using FastCGI

   When using FastCGI, Wt::Ruby requires a webserver (like apache) which
   supports FastCGI protocol.
     * Wt built with the FastGCI option enabled
     * Fastcgi or mod_fcgi plugin for apache
     * Apache (1 or 2)
       should work for other web servers as well, but the default
       configuration assumes apache when installing the library or
       deploying examples

    1b Using wthttpd

   When using the built-in webserver, Wt::Ruby only requires the Wt libwthttp
   library

     __________________________________________________________________

Building and installing the Wt::Ruby libraries and Ruby extensions

    1. Create a build directory

   The easiest way to build the library is in a seperate build directory,
   for example within the top-level of the Wt::Ruby package:
    $ cd wtruby-x.xx
    $ mkdir build
    $ cd build

    2. Configure the library

    $ 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/rdale/project/wtruby/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 .

   Variables that affect the location of dependencies are:

   Other variables specify several build and configuration aspects of Wt::Ruby,
   of which the most relevant ones are:

   Boost_VERSION
           The version number of the boost libraries that have been found,
           same as in version.hpp from Boost

   Boost_INCLUDE_DIR
           Boost include directories, this is cached and may be
           modified by advanced users

   Boost_LIBRARY_DIRS
          The path to where the Boost library files are
          lib/ and include/ are located for your boost installation.

   CMAKE_INSTALL_PREFIX
          Installation prefix for the library and include files)

   To change any entry, use [Enter]. To save and quit, do [c] followed by
   [g].

    3. Build the library

    $ make

    4. Install the library (as user with sufficient permissions):

    $ make install

    5. Get your LD_LIBRARY_PATH ok, if needed (mostly for FastCGI).

   If you did not install the Wt::Ruby 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::Ruby programs (such as the
   examples).

   Fix it by (as user with sufficient permissions):
    $ ln -s /your/path/to/lib/libwtrubyshared.so /usr/lib
    $ ln -s /your/path/to/lib/libsmokewt.so /usr/lib
    $ ln -s /your/path/to/lib/libsmokewtext.so /usr/lib

     __________________________________________________________________

Trying the examples (or your own Wt::Ruby application)

   Deploying an application is different when using FastCGI or the
   built-in web server (wthttpd).

  A. Using FastCGI and apache

    1. Deploy the example X

    $ cd examples/X
    $ ./deploy.sh

    2. Configure Apache

   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.rb

    4. Restart apache

  B. Using the wthttpd Ruby extension when WT_ENV is set to 'development'

    2. Run the example X

   Some 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 permenant
   directory). A similar argument goes for icons and the setting of the
   --docroot variable.
    $ cd ../examples/X # source directory for example X
    $ ln -s ../../resources . # include standard Wt resource files
    $ examples/X/X.rb --docroot . --http-address 0.0.0.0 --http-port 8080

   This will start a httpd server listening on all local interfaces, on
   port 8080, and you may browse the example at [2]http://127.0.0.1:8080/

   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)

   These are all the command-line options that are available:
General options:
  -h [ --help ]              produce help message
  -t [ --threads ] arg (=10) number of threads
  --docroot arg              document root for static files
  --errroot arg              root for error pages
  --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 (may be empty)

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"