czmq

CZMQ - High-level C binding for ØMQ

Linux & MacOSX	Windows

Contents

Overview

Scope and Goals

Ownership and License

Using CZMQ

Install from a package manager

• Linux
• MacOS
• Windows

Building on Linux and macOS

Building on Windows

• Using CMake
• Using MSBuild (Out of date, may not work now!)

Building for iOS

Linking with an Application

Use from Other Languages

API v3 Summary

• zactor - simple actor framework
• zauth - authentication for ZeroMQ security mechanisms
• zbeacon - LAN discovery and presence
• zcert - work with CURVE security certificates
• zcertstore - work with CURVE security certificate stores
• zchunk - work with memory chunks
• zclock - millisecond clocks and delays
• zconfig - work with config files written in rfc.zeromq.org/spec:4/ZPL.
• zdigest - provides hashing functions (SHA-1 at present)
• zdir - work with file-system directories
• zdir_patch - work with directory patches
• zfile - provides methods to work with files in a portable fashion.
• zframe - working with single message frames
• zgossip - decentralized configuration management
• zhash - simple generic hash container
• zhashx - extended generic hash container
• ziflist - list of network interfaces available on system
• zlist - simple generic list container
• zlistx - extended generic list container
• zloop - event-driven reactor
• zmonitor - socket event monitor
• zmsg - working with multipart messages
• zpoller - trivial socket poller class
• zproc - process configuration and status
• zproxy - run a steerable proxy in the background
• zrex - work with regular expressions
• zsock - high-level socket API that hides libzmq contexts and sockets
• zstr - sending and receiving strings
• zsys - system-level methods
• ztimerset - timer set
• ztrie - simple trie for tokenizable strings
• zuuid - UUID support class

Error Handling

CZMQ Actors

Under the Hood

Adding a New Class

Documentation

Development

Porting CZMQ

Hints to Contributors

Code Generation

• Docker
• Linux and MacOS

This Document

Overview

Scope and Goals

CZMQ has these goals:

• To wrap the ØMQ core API in semantics that lead to shorter, more readable applications.
• To hide as far as possible the differences between different versions of ØMQ (2.x, 3.x, 4.x).
• To provide a space for development of more sophisticated API semantics.
• To wrap the ØMQ security features with high-level tools and APIs.
• To become the basis for other language bindings built on top of CZMQ.

CZMQ grew out of concepts developed in ØMQ - The Guide.

Ownership and License

The contributors are listed in AUTHORS. This project uses the MPL v2 license, see LICENSE.

CZMQ uses the C4.1 (Collective Code Construction Contract) process for contributions.

CZMQ uses the CLASS (C Language Style for Scalabilty) guide for code style.

To report an issue, use the CZMQ issue tracker at github.com.

Using CZMQ

Install from a package manager

Linux

Deb packages are available for Debian and Ubuntu.

For other distros please refer to pkgs.org.

You can also get prebuild binaries for latest git master for most distros on openSUSE's Build Service:

Git master only stable APIs: http://software.opensuse.org/download.html?project=network%3Amessaging%3Azeromq%3Agit-stable&package=czmq

Git master including draft APIs: http://software.opensuse.org/download.html?project=network%3Amessaging%3Azeromq%3Agit-draft&package=czmq

MacOS

On macOS install czmq with Homebrew see here.

Windows

Using vcpkg

If you are already using vcpkg, you can download and install czmq with one single command:

vcpkg.exe install czmq

this will build czmq as a 32-bit shared library.

vcpkg.exe install czmq:x64-windows-static

this will build czmq as a 64-bit static library.

You may also build czmq with one or more optional libraries:

vcpkg.exe install czmq[curl,httpd,lz4]:x64-windows

this will build czmq with libcurl, libmicrohttpd, lz4, as a 64-bit shared library.

To use the draft APIs, you may build czmq with draft feature:

vcpkg install czmq[draft]

If you are an adventurer, and want to always use the latest version of czmq, pass an extra --head option:

vcpkg.exe install czmq --head

These commands will also print out instructions on how to use the library from your MSBuild or CMake-based projects.

Building on Linux and macOS

To start with, you need at least these packages:

• git -- git is how we share code with other people.
• build-essential, libtool, pkg-config - the C compiler and related tools.
• autotools-dev, autoconf, automake - the GNU autoconf makefile generators.
• cmake - the CMake makefile generators (an alternative to autoconf).

Plus some others:

• uuid-dev, libpcre3-dev - utility libraries.
• valgrind - a useful tool for checking your code.
• pkg-config - an optional useful tool to make building with dependencies easier.

Which we install like this (using the Debian-style apt-get package manager):

sudo apt-get update
sudo apt-get install -y \
    git build-essential libtool \
    pkg-config autotools-dev autoconf automake cmake \
    uuid-dev libpcre3-dev valgrind

# only execute this next line if interested in updating the man pages as well (adds to build time):
sudo apt-get install -y asciidoc

Here's how to build CZMQ from GitHub (building from packages is very similar, you don't clone a repo but unpack a tarball), including the libzmq (ZeroMQ core) library (NOTE: skip ldconfig on OSX):

git clone https://github.com/zeromq/libzmq.git
cd libzmq
./autogen.sh
# do not specify "--with-libsodium" if you prefer to use internal tweetnacl security implementation (recommended for development)
./configure --with-libsodium
make check
sudo make install
sudo ldconfig
cd ..

git clone https://github.com/zeromq/czmq.git
cd czmq
./autogen.sh && ./configure && make check
sudo make install
sudo ldconfig
cd ..

In general CZMQ works best with the latest libzmq master. If you already have an older version of libzmq installed on your system, e.g. in /usr/, then you can install libzmq master to your home directory ($HOME/local):

#   Building libzmq in our home directory
./configure --prefix=$HOME/local

And then to build CZMQ against this installation of libzmq:

export CFLAGS=-I$HOME/local/include
export LDFLAGS=-L$HOME/local/lib64
export PKG_CONFIG_PATH=$HOME/local/lib64/pkgconfig
./configure

NOTE: the PKG_CONFIG_PATH is not mandatory, and the actual directory might be different. If you cannot or do not want to use pkg-config, please make sure to MANUALLY add all the necessary CFLAGS and LDFLAGS from all dependencies (for example -DZMQ_BUILD_DRAFT_API=1 if you want the DRAFT APIs).

You will need the pkg-config, libtool, and autoreconf packages. After building, run the CZMQ selftests:

make check

Building on Windows

To start with, you need MS Visual Studio (C/C++). The free community edition works well.

Then, install git, and make sure it works from a DevStudio command prompt:

git

Using CMake

czmq requires libzmq, so we need to build libzmq first. For libzmq, you can optionally use libsodium as the curve encryption library. So we will start from building libsodium in the following (and you can bypass the building of libsodium if you are ok with libzmq's default curve encryption library):

git clone --depth 1 -b stable https://github.com/jedisct1/libsodium.git
cd libsodium\builds\msvc\build
buildall.bat
cd ..\..\..\..

Once done, you can find the library files under libsodium\bin\\\\.

Here, the `` is the platform toolset you are using: v100 for VS2010, v140 for VS2015, v141 for VS2017, etc.

git clone https://github.com/zeromq/libzmq.git
cd libzmq
mkdir build
cd build
cmake .. -DBUILD_STATIC=OFF -DBUILD_SHARED=ON -DZMQ_BUILD_TESTS=ON -DWITH_LIBSODIUM=ON -DCMAKE_INCLUDE_PATH=..\libsodium\src\libsodium\include -DCMAKE_LIBRARY_PATH=..\libsodium\bin\Win32\Release\\dynamic -DCMAKE_INSTALL_PREFIX=C:\libzmq
cmake --build . --config Release --target install
cd ..\..\

-DWITH_LIBSODIUM=ON is necessary if you want to build libzmq with libsodium. CMAKE_INCLUDE_PATH option tells libzmq where to search for libsodium's header files. And the CMAKE_LIBRARY_PATH option tells where to search for libsodium library files. If you don't need libsodium support, you can omit these three options.

-DCMAKE_INSTALL_PREFIX=C:\libzmq means we want to install libzmq into the C:\libzmq. You may need to run your shell with administrator privilege in order to write to the system disk.

Now, it is time to build czmq:

git clone https://github.com/zeromq/czmq.git
cd czmq
mkdir build
cd build
cmake .. -DCZMQ_BUILD_SHARED=ON -DCZMQ_BUILD_STATIC=OFF -DCMAKE_PREFIX_PATH=C:\libzmq
cmake --build . --config Release

Remember that we install libzmq to C:\libzmq through specifying -DCMAKE_INSTALL_PREFIX=C:\libzmq in the previous step. We here use -DCMAKE_PREFIX_PATH=C:\libzmq to tell czmq where to search for libzmq.

That is not the whole story. We didn