CppCMS Utilities
In addition to library, CppCMS provides several utilities that are used for building, running and configuring applications:
- cppcms_tmpl_cc -- templates compiler.
- cppcms_make_key -- private key generation.
- cppcms_tcp_scale -- scalability cache and sessions server.
- cppcms_run -- utility for running and debuggin CppCMS applications.
cppcms_tmpl_cc -- templates compiler
Usage:
cppcms_tmpl_cc [-o filename.cpp] [-n namespace] [-d domain] file1.tmpl ...
Switches:
-o filename.cpp--- file name that implements this template-n namespace--- setup namespace for template-d domain--- setup gettext domain for this template-h/--help--- show help message
For example:
cppcms_tmpl_cc -o view.cpp main.tmpl page.tmpl article.tmpl
Notes:
- If gettext domain specified --- it overrides default one. The default is defined by
namespace. If user defines
varyas namespace it should provide-nswitch. It is useful when you create several skins that use some shared parts.You define
anytemplate and provide switch for them, and get two copies of same template in different domains.- If no -o given, output is written to standard output.
cppcms_make_key create private key for configuration
This script uses /dev/random to create such key. You just can copy-paste it's output to the configuration file.
You may use any other tool that create cryptographically safe random set of 32 hexadecimal digits.
cppcms_tcp_scale --- scalability server
It that provides distributed backends for cache and session storage.
Usage: cppcms_tcp_scale [parameters]
Switches:
--bind IP--- ipv4/ipv6 IPto bind (default 0.0.0.0)--port N--- port to bind -- MANDATORY--threads N--- number of threads, default 1--cache--- Enable cache module--limit N--- maximal Number of items to store mandatory if cache enabled--session-files--- Enable files bases session backend--dir DIRECTORY--- Directory where files stored mandatory if session-files enabled--gc N--- gc frequencty seconds (default 600) it is enabled if threads > 1--session-sqlite3--- Enable sqlite session backend--file--- Sqlite3 DB file. Mandatory for sqlite session backend--dbfiles--- Number of DB files, default 0, 0->1 file, 1-> 2 files, 2 -> 4 files, etc
Note: At least one of --session-files, --session-sqlite3, --cache should be defined.
For example:
cppcms_tcp_scale --port 3101 --cache --limit 10000
Start cache server with one thread on port 3101 with top limit of number of entries 10,000.
Performance notes:
- This server works in fully asynchronous mode, thus generally you do not need more then 1 thread, however, you can get performance gain on multiple-cpu machines increasing this number.
- If you run several threads and sqlite3 sessions backend, increasing number of DB may improve performance.
If you are using files sessions backend, it is good idea to put it on file system that allows fast creation and deletion of multiple files.
For example: ext3 is good, XFS not good.
When running files session backend, tune gc period thus that in average it would cleanup half of all sessions --- expired. It would give you best performance of file system and GC efficiency.
- Prefer to use client side session storage or at most combined one, that would reduce access to sessions backend.
cppcms_run --- running application
This utility allows you run and debug cppcms based applications.
You need to install one of the following web servers:
- Lighttpd
- Nginx
- Apache2 with mod_fastcgi
You need to define a unix domain socket in your configuration file, for example: server.socket="/tmp/app.sock"
If you use nginx or apache, you should define server.api="fastcgi". If you use have lighttpd, you may choose "scgi" as well.
Usage
Usage cppcms_run [-e] [ -S server ] [-p port] [-h host] \
[-r /document/root ] [-s /script ]
program -c config.txt [ additional parameters ]
Switches:
-cconfiguration file of cppcms executable-p portto start the server on, default 8080-sfastcgi script name, default '/'+your program name-h hostto bind, default 127.0.0.1-rdocument root (default .)-S (lighttpd|nginx|apache2)- web server you want to run-eDo not start application, It should be started externally (for debugging)
For example:
cppcms_run hello -c config.txt
Would start a server at 127.0.0.1:8080 and the application will be accessable from "/hello" path at server.
If you do not specify webserver, cppcms_run first will try to locate ligttpd, then nginx -- asynchronous lightweight servers and then it would try to locate apache2 to run it.
Switch -e is very useful for debugging. For example:
$ cppcms_run -e app -c config.txt ... Server started $ gdb app > r -c config.txt Access violation > backtrace ...
This is simple example of running application with gdb, however you can run it with any debugger or IDE. For example, most of cppcms was written and debugged in KDevelop.
