ULib

Table of Contents

1 Getting Started With ULib

To help those curious souls that want to see if userver is a good fit for their needs I have recorded my own experiences below. Firstly a huge thankyou to Stefano Casazza not only for making ULib but for all his patience in answering all my questions.

1.1 What is userver

UServer is a extensible plugin based web server that is build on top of ULib.

ULib is installed as a set of shared object libraries and header files (like Boost).

1.2 Get a copy of the ULib source code

git clone https://github.com/stefanocasazza/ULib.git

1.3 configure your build

For those of you like me who havn't had much experience playing with autotools read the config help or:

./configure -h

Having now decided on what features you need let ./configure do its magic.

For example: ./configure –enable-debug –with-sqlite3

make sudo make install

1.4 configure userver

Assuming you haven't changed the PREFIX make will install userver to /usr/local

At this point we need to configure /usr/local/etc/userver.cfg The file is well annotated at a bare minimum setup the following values:
DOCUMENT_ROOT /var/www
LOG_FILE userver.log
PLUGIN "http"
PLUGIN_DIR /usr/local/libexec
ORM_DRIVER_DIR /usr/local/libexec

This environment variables are for ORM management:
ORM_DRIVER "sqlite"
ORM_OPTION "host=localhost user=user password=pass character-set=utf8 dbname=/path_to_db/dbname.db"

1.5 debug environment

userver_tcp expects some environment variables for debug mode to save typing it is easiest to put these into a bash script like this:

#!/bin/sh

UTRACE="0 20M 0"
UTRACE_SIGNAL="0 20M 0"
#UOBJDUMP="0 10M 100"
#USIMERR="error.sim"
export UTRACE UOBJDUMP USIMERR UTRACE_SIGNAL

userver_tcp

1.6 Running your server (static pages)

Once you have configured your userver.cfg and placed the relevant html documents in your docroot just execute the bash script above.

Point your browser to localhost/filename you should now have a working server.

1.7 USP ULib Servlet Page (dynamic pages)

userver offers a wide variety of ways to generate dynamic content we will be looking at USP method.

A USP page is a multi-format document that permits c++ code to be embedded into html. This document is then compiled into a shared object library that will be executed by userver.

The document consists of overloaded html comment tags that the USP compiler will extract.

1.8 Tags

Have a look at the examples in the ULib source directory ULib/src/ulib/net/server/plugin/usp for usage but in very simple terms.

1.8.1 c++ header file .h

<!–#declaration –>

1.8.2 c++ code file .cpp

<!–#code UString name = U_STRING_FROM_CONSTANT("Hello World"); –>

1.8.3 html template

<h1>Hello <!–#xmlputs name –></h1>

1.9 Compiling

Once you have written your .usp file it needs to be compiled. I found it easiest to navigate to the folder where the file.usp was saved and execute the compilation in the shell for example:

cd /srv/http/servlet /usr/local/bin/usp_compile.sh test

Please note that usp_compile.sh wants the usp file without the extension. The shell script will call the relevant programs to generate c++ code from the usp file and finally call gcc and libtool to create a shared library.Any compilation errors will be output to console and no .so file will be generated.

It would be trivial to execute usp_compile as a custom command from most IDEs.

1.10 Test

Now point your browser to localhost/nameofusp and userver will execute the USP file.

1.11 SECURITY

As with all web servers do not run them as the root user. This introduction has been written to give you an idea of the ULib/UServer workflow. It is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. It is your responsibility to secure your web server and follow sound security conscious programming practices.

Author: nemsys

Created: 2017-05-07 Sun 13:21

Emacs 25.2.1 (Org mode 8.2.10)

Validate