NAME

psmq_building - information about building psmq library.

DESCRIPTION

psmq is targeted mainly for small embedded systems which do not have advanced IPC like unix domain sockets. It doesn't have much usecases (if any) on big OSes like Linux - there are far more advanced solutions for such systems. psmq library cares mainly about memory and runtime safety. It can be build and run on every UNIX though to make application developemt and testing much easier - you can write and test your app on UNIX system and then just move it to embedded posix-compliant system without changes.

To avoid dynamic memory allocation as much as possible, most options are set during compile time, and since this is mainly for embedded systems - it's not a problem.

PASSING SETTINGS

Depending on how you want to compile this software, there are a few ways to define settings.

AUTOTOOLS

If you build for UNIX system, it's the easiest and best way to install psmq library and programs. Settings are passed to configure script as environment variables like that

    PSMQ_MAX_CLIENTS=128 PSMQ_MSG_MAX=64 ./configure

And of course after that, there is standard "make" and "make install". You're done.

COMPILER DEFINITIONS

If you integrate psmq into bare metal embedded system without OS, you can just define options. How you do it heavily depends on your build system. For cmake, you could use

    add_definitions(-DPSMQ_MAX_CLIENTS=128 -DPSMQ_MSG_MAX=32)

If you are using "make" based build system, you would use something along the lines

    CFLAGS += -DPSMQ_MAX_CLIENTS=128
    CFLAGS += -DPSMQ_MSG_MAX=64

CONFIG FILE

You can also define all of those values in psmq-config.h file. That file should be directly accessible by compiler - every source file includes this file this way:

    #ifdef HAVE_CONFIG_H
    #   include "psmq-config.h"
    #endif

You also must define HAVE_CONFIG_H. To define options, you just do classic C definitions

    #define PSMQ_MAX_CLIENTS 128
    #define PSMQ_MSG_MAX 64

COMPILATION OPTIONS

PSMQ_MAX_CLIENTS (int): This defines how many clients single broker process will support. Broker will return error for clients that want to register to it and there are already max clients connected. psmqd will alocate client array with static storage duration that is about 12 bytes (may vary depending on architecture) for each client.
PSMQ_MSG_MAX (int): Defines maximum size of topic + payload that can be sent via psmq. Topic and payload are sent in a single buffer, so they share memory. This allows for some flexibility, as you can send one message with big topic name, but no payload data and another message can have short topic, but much more payload. This option has direct impact on memory usage of broker and library. But even if you set this to high value, only actual payload will be sent. So you could set PSMQ_MSG_MAX to 1024 bytes, send message on topic "/t" and one byte of payload, and then only 4 bytes and not 1024 will be copied over mqueue.

PSMQ_NO_SIGNALS (bool): Signals were implemented mainly for full-fledged UNIXes, but many embedded simply does not implement signals. If you want to use psmq on such system, define this to 1. It is not possible to set this when building with autotools. C'mon, if you can use autotools you surely have signals.

DEPENDENCIES

Broker and psmq-sub need >=embedlog-v0.6.0 for logging. It can be downloaded from https://embedlog.bofc.pl