In addition to library, CppCMS provides several utilities that are used for building, running and configuring applications: |
|
- [cppcms\_tmpl\_cc](#tmpl) -- templates compiler. |
- [cppcms\_make\_key](#make) -- private key generation. |
- [cppcms\_tcp\_scale](#tcp) -- scalability cache and sessions server. |
- [cppcms\_run](#run) -- utility for running and debuggin CppCMS applications. |
|
|
## <span id="tmpl"></span>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 main.tmpl page.tmpl article.tmpl view.cpp |
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 `vary` as namespace it should provide `-n` switch. It is useful when you create several skins that use some shared parts. |
|
You define `any` template 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. |
|
## <span id="make"></span>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. |
|
## <span id="tcp"></span>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. |
|
|
|
## <span id="run"></span>cppcms\_run --- running application |
|
This utility allows you run and |
debug cppcms based applications. |
|
You need to install one of the following web servers: |
|
1. [Lighttpd](http://lighttpd.net) |
2. [Nginx](http://www.nginx.net/) |
3. [Apache2](http://httpd.apache.org/) with [mod_fastcgi](http://www.fastcgi.com/mod_fastcgi/docs/mod_fastcgi.html) |
|
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: |
|
- `-c` configuration file of cppcms executable |
- `-p port` to start the server on, default 8080 |
- `-s` fastcgi script name, default '/'+your program name |
- `-h host` to bind, default 127.0.0.1 |
- `-r` document root (default .) |
- `-S (lighttpd|nginx|apache2)` - web server you want to run |
- `-e` Do 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. |
|
|
|
