Created Getting Started With ULib (markdown)

Getting-Started-With-ULib.md

@@ -0,0 +1,96 @@
+# Getting Started With UServer/ULIB
+To help others curious to see if UServer/ULIB is a good fit for their needs I have recorded my own expereince. 
+Firstly a huge thankyou to Stefano Casazza not only for making Ulib but for all his patience in answering all my questions. 
+
+## 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).
+
+## Get a copy of the ULib source code
+git clone https://github.com/stefanocasazza/ULib.git
+
+## configure your build
+If you 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
+
+## 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 
+    LOG_FILE 
+    PLUGIN "http" 
+    PLUGIN_DIR /usr/local/libexec
+    ORM_DRIVER_DIR /usr/local/libexec
+    ORM_DRIVER "sqlite"
+    ORM_OPTION "host=${DBHOST} user=user password=pass character-set=utf8 dbname=/path to db/dbname.db"
+  
+## 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 -1"
+    UTRACE_SIGNAL="0 20M -1"
+    #UOBJDUMP="0 10M 100"
+    #USIMERR="error.sim"
+    export UTRACE UOBJDUMP USIMERR UTRACE_SIGNAL
+
+    userver_tcp
+
+## 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.
+
+## 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.
+
+## 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.
+
+### c++ header file .h
+    <!--#declaration
+    -->
+
+### c++ code file .cpp
+    <!--#code
+    UString name = U_STRING_FROM_CONSTANT("Hello World");
+    -->
+
+### html template
+    <h1>Hello <!--#xmlputs name --></h1>
+
+## 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.
+
+## Test
+Now point your browser to localhost/nameofusp and userver will execute the USP file.
+
+## 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.