Commit 621549b3 authored by Felix Hamann's avatar Felix Hamann

gitlab does not render links

parent e4922d89
[![Samwise CI Build Status](http://ci.ramlimit.de/job/samwise/badge/icon)](https://ci.ramlimit.de/job/samwise)
# SAMWISE #
Samwise the stout-hearted. A store and forward messaging service.
![Samwise Threads](../img/sam_threads.png)
Please see the source code commentary for a thorough explanation of the different modules and the issue tracker for current bugs and planned features.
## Installation ##
```
./autogen.sh
make
```
This compiles `samd`, `sam_selftest` and `libsam.so`. The library `libsam` gets linked statically to the binaries. The dependencies are linked dynamically and you are responsible for their proper installation.
## Running Tests ##
There are custom make targets to run the tests. To run all tests (unit and integration) while automagically start other things like brokers run `make test_integrated` (`sudo` is going to be invoked). When running `make test`, make sure to have a RabbitMQ broker started on port `15672`. To just run all unit tests invoke `make test_unit`. Sometimes, when running all test suites, ZeroMQ related assertions fail. I suspect a problem with opening and closing a lot of ZeroMQ sockets.
While developing some feature, it is often more useful to just run the specific modules' tests (or even just a testcase of the modules' test suite). To do so `sam_selftest` must be invoked directly.
```
~/C/s/s/samwise [master]
▸ ./sam_selftest -h
sam selftest
usage: sam_selftest [-h] [--only SAM_MODULE [TESTCASE]]
options:
-h: Print this message and exit
--only SAM_MODULE [TESTCASE]:
selective running of tests, where SAM_MODULE is one of
{ sam_gen, sam_log, sam_msg, sam_cfg, sam_be_rmq, sam }
and TESTCASE one of the test cases defined in SAM_MODULE
You can selectively run tests by setting the CK_RUN_SUITE and
CK_RUN_CASE environment variables instead of providing --only
```
### Send All Messages Daemon (samd) ###
The main program. You need to provide a configuration file for proper execution. You can find examples of configuration files in the /samwise/cfg directory and its subdirectories. To control the verbosity of the logging you (currently and unfortunately) need to change the log threshold in `include/sam.h`.
```
./samd cfg/base.cfg
```
### Sam Control Interface (samctl) ###
The control interface is used to communicate with a running samwise daemon instance.
```
~/C/s/s/samwise [master]
▸ ./samctl --help
Usage: samctl [OPTION...] COMMAND
___ __ _ _ ____ __ _(_)___ ___ __ ___ _ _| |_ _ _ ___| |
(_-</ _` | ' \ V V / (_-</ -_) / _/ _ \ ' \ _| '_/ _ \ |
/__/\__,_|_|_|_\_/\_/|_/__/\___| \__\___/_||_\__|_| \___/_|
Currently the following commands are supported:
ping Ping samwise
status Get extensive status information about samd's state
stop Order samd to kill itself
restart Restart samd
Additionally the following options can be provided:
-c, --config=CFG Specify a configuration file (or use -e)
-e, --endpoint=ENDPOINT Specify the endpoint (or use -c)
-q, --quiet Suppress output
-v, --verbose Verbose output
-?, --help Give this help list
--usage Give a short usage message
-V, --version Print program version
Mandatory or optional arguments to long options are also mandatory or optional
for any corresponding short options.
Report bugs to http://github.com/dreadworks/samwise/issues.
```
For example, to get more information about the current state of the daemon, use the "status" command:
```
~/C/s/s/samwise [master]
▸ ./samctl -c cfg/base.cfg status
BACKENDS:
1 backend(s) registered:
broker-1 (id: 0x1) (localhost:5672 as 'guest'):
connected: yep (3/3 tries every 5000ms)
heartbeat: every 3 seconds
current sequence number: 2
pending acks: 0
METRICS:
samd:
valid requests: 1
accepted requests: 2
sam:
publishing requests (total): 1
publishing requests (distributed): 1
publishing requests (clients): 1
buffer:
acknowledgments: 1
created records: 1
```
## Dependencies ##
### Building samwise ###
Samwise relies on some libraries:
| Library name | Version |
|----------------------------------------------------|----------|
| [ZeroMQ](http://zeromq.org/) | 4.0.5 |
| [CZMQ](http://czmq.zeromq.org/) | 3.0.0 |
| [Berkeley DB](http://www.oracle.com/technetwork/database/database-technologies/berkeleydb/overview/index.html)| >= 5.1 |
| [RabbitMQ-C](https://github.com/alanxz/rabbitmq-c) | 0.5.2 |
### Render documentation ###
To render the documentation the program `doxygen` is used. The rendered documentation can be found in `/samwise/doc/*`.
## Tools ##
### Description ###
Currently there are a number of shell script files inside the `samwise/tools` directory. As their suffix hints, they are written for the [fish shell](fishshell.com). You can safely run them like `. tools/script.fish argument1`. Please see below for a documentation of the various scripts.
### Install dependencies locally - deps.fish ###
This script automatically downloads all libraries samwise depends on and installs them into the projects root directory. It creates a folder `/usr` used as the prefix to build all dependencies. Additionally, to be able to compile and link against the local installations, all required environmental veriables are set.
```bash
. tools/deps.fish
```
### Create a TAGS file - tags.fish ###
To efficiently jump to function definitions with emacs using `find-tag` and its friends, a TAGS file must be generated using the `etags` program. To build the symbol table and access the files containing the definitions and declarations, `tags.fish` clones all dependencies into `/.tags` and creates `/samwise/TAGS`.
```bash
. tools/tags.fish
```
### Release a new version - release.fish ###
This script updates all places where version numbers are used. Currently the touched files are `include/sam.h`, `Doxyfile` and `configure.ac`. A new `configure.scan` is created for this purpose. You can call it like this:
```bash
. tools/release.fish major minor patch [cflags]
# where major, minor and patch are numbers
# for example
. tools/release.fish 1 0 3
```
## Project Setup ##
### Code and Project Conventions ###
This project uses the [C Language Style for Scalability (CLASS)](http://rfc.zeromq.org/spec:21) code and project structure conventions. The projects name is `samwise`, the project abbreviation `sam` and the project prefix `sam_`. The specification applies to everything inside the `/samwise` directory. The C language level is C99.
### Constrictions of the CLASS spec ###
I wholeheartedly disagree that omitting the curly braces for one-line if statements is a good idea. So I'm going to break the CLASS spec for if statements:
```C
// always like this, please:
if (condition) {
// ...
}
```
README.md
\ No newline at end of file
README
\ No newline at end of file
[![Samwise CI Build Status](http://ci.ramlimit.de/job/samwise/badge/icon)](https://ci.ramlimit.de/job/samwise)
# SAMWISE #
Samwise the stout-hearted. A store and forward messaging service.
![Samwise Threads](../img/sam_threads.png)
Please see the source code commentary for a thorough explanation of the different modules and the issue tracker for current bugs and planned features.
## Installation ##
```
./autogen.sh
make
```
This compiles `samd`, `sam_selftest` and `libsam.so`. The library `libsam` gets linked statically to the binaries. The dependencies are linked dynamically and you are responsible for their proper installation.
## Running Tests ##
There are custom make targets to run the tests. To run all tests (unit and integration) while automagically start other things like brokers run `make test_integrated` (`sudo` is going to be invoked). When running `make test`, make sure to have a RabbitMQ broker started on port `15672`. To just run all unit tests invoke `make test_unit`. Sometimes, when running all test suites, ZeroMQ related assertions fail. I suspect a problem with opening and closing a lot of ZeroMQ sockets.
While developing some feature, it is often more useful to just run the specific modules' tests (or even just a testcase of the modules' test suite). To do so `sam_selftest` must be invoked directly.
```
~/C/s/s/samwise [master]
▸ ./sam_selftest -h
sam selftest
usage: sam_selftest [-h] [--only SAM_MODULE [TESTCASE]]
options:
-h: Print this message and exit
--only SAM_MODULE [TESTCASE]:
selective running of tests, where SAM_MODULE is one of
{ sam_gen, sam_log, sam_msg, sam_cfg, sam_be_rmq, sam }
and TESTCASE one of the test cases defined in SAM_MODULE
You can selectively run tests by setting the CK_RUN_SUITE and
CK_RUN_CASE environment variables instead of providing --only
```
### Send All Messages Daemon (samd) ###
The main program. You need to provide a configuration file for proper execution. You can find examples of configuration files in the /samwise/cfg directory and its subdirectories. To control the verbosity of the logging you (currently and unfortunately) need to change the log threshold in `include/sam.h`.
```
./samd cfg/base.cfg
```
### Sam Control Interface (samctl) ###
The control interface is used to communicate with a running samwise daemon instance.
```
~/C/s/s/samwise [master]
▸ ./samctl --help
Usage: samctl [OPTION...] COMMAND
___ __ _ _ ____ __ _(_)___ ___ __ ___ _ _| |_ _ _ ___| |
(_-</ _` | ' \ V V / (_-</ -_) / _/ _ \ ' \ _| '_/ _ \ |
/__/\__,_|_|_|_\_/\_/|_/__/\___| \__\___/_||_\__|_| \___/_|
Currently the following commands are supported:
ping Ping samwise
status Get extensive status information about samd's state
stop Order samd to kill itself
restart Restart samd
Additionally the following options can be provided:
-c, --config=CFG Specify a configuration file (or use -e)
-e, --endpoint=ENDPOINT Specify the endpoint (or use -c)
-q, --quiet Suppress output
-v, --verbose Verbose output
-?, --help Give this help list
--usage Give a short usage message
-V, --version Print program version
Mandatory or optional arguments to long options are also mandatory or optional
for any corresponding short options.
Report bugs to http://github.com/dreadworks/samwise/issues.
```
For example, to get more information about the current state of the daemon, use the "status" command:
```
~/C/s/s/samwise [master]
▸ ./samctl -c cfg/base.cfg status
BACKENDS:
1 backend(s) registered:
broker-1 (id: 0x1) (localhost:5672 as 'guest'):
connected: yep (3/3 tries every 5000ms)
heartbeat: every 3 seconds
current sequence number: 2
pending acks: 0
METRICS:
samd:
valid requests: 1
accepted requests: 2
sam:
publishing requests (total): 1
publishing requests (distributed): 1
publishing requests (clients): 1
buffer:
acknowledgments: 1
created records: 1
```
## Dependencies ##
### Building samwise ###
Samwise relies on some libraries:
| Library name | Version |
|----------------------------------------------------|----------|
| [ZeroMQ](http://zeromq.org/) | 4.0.5 |
| [CZMQ](http://czmq.zeromq.org/) | 3.0.0 |
| [Berkeley DB](http://www.oracle.com/technetwork/database/database-technologies/berkeleydb/overview/index.html)| >= 5.1 |
| [RabbitMQ-C](https://github.com/alanxz/rabbitmq-c) | 0.5.2 |
### Render documentation ###
To render the documentation the program `doxygen` is used. The rendered documentation can be found in `/samwise/doc/*`.
## Tools ##
### Description ###
Currently there are a number of shell script files inside the `samwise/tools` directory. As their suffix hints, they are written for the [fish shell](fishshell.com). You can safely run them like `. tools/script.fish argument1`. Please see below for a documentation of the various scripts.
### Install dependencies locally - deps.fish ###
This script automatically downloads all libraries samwise depends on and installs them into the projects root directory. It creates a folder `/usr` used as the prefix to build all dependencies. Additionally, to be able to compile and link against the local installations, all required environmental veriables are set.
```bash
. tools/deps.fish
```
### Create a TAGS file - tags.fish ###
To efficiently jump to function definitions with emacs using `find-tag` and its friends, a TAGS file must be generated using the `etags` program. To build the symbol table and access the files containing the definitions and declarations, `tags.fish` clones all dependencies into `/.tags` and creates `/samwise/TAGS`.
```bash
. tools/tags.fish
```
### Release a new version - release.fish ###
This script updates all places where version numbers are used. Currently the touched files are `include/sam.h`, `Doxyfile` and `configure.ac`. A new `configure.scan` is created for this purpose. You can call it like this:
```bash
. tools/release.fish major minor patch [cflags]
# where major, minor and patch are numbers
# for example
. tools/release.fish 1 0 3
```
## Project Setup ##
### Code and Project Conventions ###
This project uses the [C Language Style for Scalability (CLASS)](http://rfc.zeromq.org/spec:21) code and project structure conventions. The projects name is `samwise`, the project abbreviation `sam` and the project prefix `sam_`. The specification applies to everything inside the `/samwise` directory. The C language level is C99.
### Constrictions of the CLASS spec ###
I wholeheartedly disagree that omitting the curly braces for one-line if statements is a good idea. So I'm going to break the CLASS spec for if statements:
```C
// always like this, please:
if (condition) {
// ...
}
```
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment