CZMQ 技术文档

本文档将详细介绍如何安装、使用及API调用CZMQ项目。CZMQ是ZeroMQ（ØMQ）的高级别C语言绑定库，旨在简化ØMQ的使用并提供更加易于理解的高级API。

1. 安装指南

1.1 使用包管理器安装

Linux

在Debian和Ubuntu系统中，可以通过包管理器直接安装CZMQ：

sudo apt-get install czmq

对于其他发行版，可以参考packages.org获取安装包。

也可以在openSUSE的构建服务上获取最新git master分支的预编译二进制文件：

• 仅包含稳定API的Git master分支： http://software.opensuse.org/download.html?project=network%3Amessaging%3Azeromq%3Agit-stable&package=czmq
• 包含草稿API的Git master分支： http://software.opensuse.org/download.html?project=network%3Amessaging%3Azeromq%3Agit-draft&package=czmq

MacOS

在macOS上，可以使用Homebrew安装CZMQ：

brew install czmq

Windows

如果使用vcpkg，可以通过以下命令下载和安装CZMQ：

vcpkg install czmq

此命令将构建32位共享库。以下是构建64位静态库的命令：

vcpkg install czmq:x64-windows-static

还可以选择安装包含可选库的CZMQ：

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

若要使用草稿API，请在安装时添加draft特性：

vcpkg install czmq[draft]

若要始终使用最新版本的CZMQ，请添加--head选项：

vcpkg install czmq --head

这些命令还将打印出如何在MSBuild或CMake项目中使用库的说明。

1.2 在Linux和macOS上构建

首先，需要以下软件包：

• git -- 用于与其他人共享代码。
• build-essential, libtool, pkg-config -- C编译器和相关工具。
• autotools-dev, autoconf, automake -- GNU autoconf makefile生成器。
• cmake -- CMake makefile生成器（autoconf的替代品）。

以及其他一些软件包：

• uuid-dev, libpcre3-dev -- 实用库。
• valgrind -- 用于检查代码的工具。
• pkg-config -- 使依赖项构建更简单的可选工具。

在Debian风格的系统中，可以这样安装：

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

# 如果需要更新手册页（会增加构建时间），请执行以下命令：
sudo apt-get install -y asciidoc

以下是如何从GitHub构建CZMQ的步骤（从包构建非常相似，不同之处在于解压缩tarball而不是克隆仓库），包括libzmq（ZeroMQ核心库）：

git clone https://github.com/zeromq/libzmq.git
cd libzmq
./autogen.sh
./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 ..

通常，CZMQ与最新的libzmq master分支配合使用效果最佳。如果系统中已安装较旧的libzmq版本，例如在/usr/目录下，则可以：

# 在系统上安装较旧版本的libzmq
sudo apt-get install libzmq3-dev

2. 项目的使用说明

CZMQ提供了一系列高级API，用于简化ZeroMQ的消息传递操作。使用CZMQ，开发者可以轻松创建消息框架、安全认证、网络发现等功能。

以下是一个简单的示例，展示如何使用CZMQ创建一个Réactor模式的消息处理程序：

#include <czmq.h>

int main(void) {
    zactor_t *server = zactor_new(zserver, NULL);
    zsock_send(server, "ss", "BIND", "tcp://*:5555");

    zactor_t *client = zactor_new(zclient, NULL);
    zsock_send(client, "ss", "CONNECT", "tcp://localhost:5555");

    // 等待消息
    zmsg_t *request = zactor_recv(client);
    if (request) {
        zmsg_print(request);
        zmsg_destroy(&request);
    }

    zactor_destroy(&server);
    zactor_destroy(&client);
    return 0;
}

3. 项目API使用文档

CZMQ提供了丰富的API，以下是一些核心类的简要描述：

• zactor: 简单的Actor框架。
• zauth: ØMQ安全机制的认证。
• zbeacon: 局域网发现和存在。
• zcert: 适用于CURVE安全证书的操作。
• zchunk: 内存块操作。
• zclock: 毫秒级时钟和延迟。
• zconfig: 处理以rfc.zeromq.org/spec:4/ZPL格式编写的配置文件。
• zdigest: 提供散列函数（目前为SHA-1）。
• zdir: 文件系统目录操作。
• zfile: 提供以可移植方式处理文件的方法。
• zframe: 单个消息帧操作。
• zgossip: 去中心化配置管理。
• zhash: 简单的通用哈希容器。
• zlist: 简单的通用列表容器。
• zloop: 事件驱动的Réactor。
• zmonitor: 套接字事件监控。
• zmsg: 多部分消息操作。
• zpoller: 简单的套接字轮询器类。
• zproxy: 在后台运行可 steer 的代理。
• zsock: 隐藏libzmq上下文和套接字的顶层套接字API。
• zstr: 发送和接收字符串。
• zsys: 系统级方法。
• ztimerset: 定时器集。
• ztrie: 简单的可标记字符串trie。
• zuuid: UUID支持类。

具体API的使用方法和示例代码，请参考CZMQ的官方文档和示例。

4. 项目安装方式

CZMQ可以通过多种方式安装，以下是一些常见的安装方法：

• 使用包管理器（如上所述）。
• 从源代码构建（如上所述）。
• 使用容器（如Docker）。

请根据具体的操作系统和环境选择合适的安装方式。