To build RTIMDB, you need each of the following:
- CMake (we use version 3.2)
- one of the following compilers:
- Microsoft Visual Studio 2015 or later
- GCC 4.7 or later
- Clang 3.3 or up should work, but is not regularly tested
- C++11 - modern C++ constructs are used throughout the code, including a few library features. We have portable equivalents of the library features if you need them, but those are not free software.
RTIMDB uses no external libraries.
For any build, we recommend building out-of-tree (it makes it easier to distinguish generated files from non-generated files, and thus makes version control that much easier).
In the following, a
$ indicates a non-privileged user command-line command on
a shell such as Bash. If you're working on a Windows system, these should still
work but there are usually GUI equivalents - which will be indicated.
Get the source
The Open Source, Apache-licensed version of RTIMDB is available on GitHub. We
recommend using a tagged version as they've been most thoroughly tested, but
master branch will usually compile and run without problems as well.
$ git clone https://github.com/VlinderSoftware/rtimdb.git ... clones into rtimdb directory $ cd rtimdb $ git checkout -b <name of your project> <tag-name>
GitHub has a GUI client that you can use to clone the repository directly from the site. Otherwise, you can also download a zip archive of the latest version, or of any version you want.
Configuring the build
$ mkdir .build $ cd .build $ ccmake ..
This will start a Curses interface for CMake, which will allow you to configure the settings you want.
We recommend using cmake-gui, which comes with the CMake package.
The configuration options
By default, the project will build several different configurations of the
database, with various flags set or cleared, both for testing and demonstration
purposes. The first version it will build will be called
rtimdb and will have
the configuration you give it; the other versions will have default configurations
with some tweaks (with and without exception support, for example).
The things you can configure are:
- BUILD_TESTING: if turned off, the various unit tests won't be built.
- RTIMDB_ALLOW_EXCEPTIONS: if turned on, the database will have an interface
that throws exceptions in certain error cases, as well as an equivalent
interface that doesn't. If turned off, the database will never throw an
exception but will return error codes in stead.
Even for embedded devices, we recommend turning exceptions on as it allows for more robust code (it is impossible to ignore an exception), but as many don't agree with this particular recommendation, the entire database code is written to allow for exceptions to be turned off. The code remains exception-safe in either case.
- RTIMDB_COMMAND_QUEUE_CAPACITY: determines the size of the command queues. Normally, there is one command queue for every "producer", which serves to send commands to the outputs of a system (e.g. opening or closing a relay). By default, the size of this queue is 16 (enough for 16 commands). As commands are usually relatively rare but come in pairs (select and operate), we recommend a size of twice the number of outputs in the system.
- RTIMDB_EVENT_QUEUE_CAPACITY: determines the size of the event queues. There may be several event queues for each consumer, depending on how many event classes you want to support (there are three by default). The size you need depends on the frequency at which events are reported over the communications links, and whether your protocol stack has its own event queues as well (in which case the one in the database can be a lot smaller).
- RTIMDB_TRANSITION_QUEUE_CAPACITY: determines the size of the transition queues. There is one transition queue per producer, into which it pushes the transitions. The size of these will depend on the frequency with which the device polls its inputs, how those inputs are debounced, etc.
- RTIMDB_MAX_CONCURRENT_TRANSACTIONS: determines the number of transactions that can take place at the same time in the database. This usually corresponds to the maximum number of consumers, plus one if you use a separate database update task.
- RTIMDB_MAX_CONSUMER_COUNT: determines the maximum number of consumers, which are usually either communication protocol (slave) instances or PLC cores.
- RTIMDB_MAX_PRODUCER_COUNT: determines the maximum number of producers, which are usually either I/O scan tasks or PLC cores (but may sometimes also be communication protocol (master) instances).
- RTIMDB_MAX_TRANSITIONS_PER_TRANSACTION: determines the maximum number of transitions a single producer transaction may contain.
- RTIMDB_POINT_COUNT: determines the maximum number of points in the database.
- RTIMDB_MAPPING: determines the way mappings are handled on the consumer's side. There are currently two options: the Default option, which is to handled them as a list of tag-to-system-id mappings in which ever order they are added to the mapping; and the Sorted option, which constructs the mapping as two ordered lists of tag-to-system-id and system-id-to-tag mappings. With the former, both constructing the mapping and searching through it are O(n); with the latter, constructing it is O(n lg(n)) and searching through it is O(lg(n)).
The memory footprint of the database in the device depends entirely on the points count, the number of concurrent transactions that can take place an the sizes and number of the different queues. The best values for these settings depend heavily on your specific application.
Depending on the settings you choose, some of the unit tests may not compile with your configuration: there are static assertions in the unit tests to verify that certain assumptions regarding the sizes of the queues hold (for tests that test queue overflow conditions, for example). This is not a problem per se: it just means that if you want to test these conditions, you may have to tweak the test cases a bit for the parameters you choose. Feel free to contact us if you need any help (the static assertion message contains the appropriate E-mail address to use).
To run the unit tests:
$ make test
The CMake process will have created a .sln file. Open in and hit Build (usually
To run the unit tests, build the RUN_TESTS target.