All Products
Search

This Product

    ApsaraMQ for RocketMQ:Set up the C++ SDK (V1.x.x)

    Document Center

    ApsaraMQ for RocketMQ:Set up the C++ SDK (V1.x.x)

    Last Updated:Mar 11, 2026

    Set up your Linux or Windows development environment to send and receive messages with the ApsaraMQ for RocketMQ C++ SDK V1.x.x.

    Prerequisites

    Before you begin, make sure you have:

    • An Alibaba Cloud account with ApsaraMQ for RocketMQ activated

    • Topics and consumer groups created in the ApsaraMQ for RocketMQ console

    • An Elastic Compute Service (ECS) instance for deploying your application

    Important

    This guide covers the C++ SDK V1.x.x only. Message tags are application-defined and do not require console configuration.

    Download the SDK

    The C++ SDK supports Windows and Linux with identical interfaces. On Linux, CentOS 6 (RHEL 6) and CentOS 7 (RHEL 7) are supported.

    Download the SDK package from the release notes page.

    Package contents

    After you extract the package, the directory contains the following:

    Directory or fileDescription
    demo/Pre-configured Visual Studio project (Windows only)
    example/Sample code for sending and consuming normal, one-way, and ordered messages. On Linux, includes a Makefile
    include/Header files for your application
    lib/Static and shared libraries (see details below)
    SDK_GUIDE.pdfSDK environment setup guide and FAQ
    changelogBug fixes and new features per release

    Library files

    Linux

    PathFileType
    lib/lib-boost-static/libonsclient4cpp.aStatic library with Boost statically linked
    lib/lib-boost-share/libonsclient4cpp.soShared library (requires Boost shared libraries)

    Windows

    PathFileDescription
    lib/64/SDK DLL64-bit dynamic library
    lib/vc_redist.x64Visual C++ 2015 runtime. Install this if Visual Studio 2015 is not present

    Set up the Linux environment

    Since December 2, 2016, the Linux C++ SDK depends on Boost 1.62.0 for lower CPU usage and better throughput.

    The SDK requires the following Boost libraries:

    LibraryRequired
    boost_systemYes
    boost_threadYes
    boost_chronoYes
    boost_filesystemYes

    Choose one of the following linking strategies based on your project requirements.

    Option 1: Static linking (recommended)

    Use this option if your project does not already depend on Boost. The static library at lib/lib-boost-static/libonsclient4cpp.a bundles all four Boost libraries, so no separate Boost installation is needed.

    Build with the included Makefile

    cd aliyun-mq-linux-cpp-sdk    # Root of the extracted SDK
cd example                     # Edit the example file to set your topic and access key
make static=1
    Important

    A fully static build requires libstdc++.a, libpthread.a, and related static libraries. By default, libstdc++ ships without a static library on most distributions. Install the required static libraries through yum or apt-get.

    A fully static build may produce the following warning:

    warning: Using 'gethostbyaddr' in statically linked applications requires at runtime
the shared libraries from the glibc version used for linking

    Recommended approach: statically link only the SDK

    To avoid this warning, statically link libonsclient4cpp while keeping system libraries dynamically linked:

    g++ -ggdb -Wall -O3 -I../include \
    ../example/ProducerExampleForEx.cpp \
    -Wl,-static -lonsclient4cpp -L../lib/lib-boost-static/ \
    -Wl,-Bdynamic -lpthread -ldl -lrt \
    -o ../example/ProducerExampleForEx
    Note

    If you compile with GCC 5.x or later, add the -D_GLIBCXX_USE_CXX11_ABI=0 flag due to the Dual ABI change introduced in GCC 5.

    Option 2: Dynamic linking

    Use this option if your project already depends on Boost or if you prefer shared libraries. This requires a local Boost 1.62.0 installation.

    Step 1: Install Boost 1.62.0

    1. Download Boost 1.62.0.

    2. Extract the archive:

         tar --bzip2 -xf /path/to/boost_1_62_0.tar.bz2

    3. Build and install Boost:

         cd path/to/boost_1_62_0
   ./bootstrap.sh
   ./b2 link=shared runtime-link=shared
   ./b2 install

    4. Verify that the Boost shared libraries are in the linker search path: If no output appears, add the Boost library path to /etc/ld.so.conf and run ldconfig.

         ldconfig -v | grep libboost

    Step 2: Build your application

    cd aliyun-mq-linux-cpp-sdk    # Root of the extracted SDK
cd example                     # Edit the example file to set your topic and access key

g++ -Wall -Wno-deprecated \
    -L ../lib/lib-boost-share/ -I ../include/ \
    ProducerExampleForEx.cpp \
    -lonsclient4cpp -lboost_system -lboost_thread -lboost_chrono -lboost_filesystem \
    -lpthread

export LD_LIBRARY_PATH="../lib/lib-boost-share/"
./a.out

    Set up the Windows environment

    Visual Studio 2015

    1. Create a new project in Visual Studio 2015.

    2. Open Configuration Manager and set:

      • Active solution configuration to release

      • Active solution platform to x64

    3. Configure the output directory:

      • Go to Properties > Configuration Properties > General.

      • Set Output Directory to a directory of your choice, for example C:\myproject\output.

      • Copy all files from the SDK lib\64\ directory into the output directory.

    4. Configure include paths:

      • Go to Properties > Configuration Properties > C/C++ > General.

      • Add a directory to Additional Include Directories, for example C:\myproject\include.

      • Copy the SDK include\ header files into this directory.

    5. Configure library paths:

      • Go to Properties > Configuration Properties > Linker > General.

      • Add the output directory from step 3 to Additional Library Directories.

    6. Add the SDK library dependency:

      • Go to Properties > Configuration Properties > Linker > Input.

      • Add ONSClient4CPP.lib to Additional Dependencies.

    7. Add the preprocessor macro:

      • Go to Properties > Configuration Properties > C/C++ > Preprocessor.

      • Add WIN32 to Preprocessor Definitions.

    8. Click Build to compile. Before running the executable, copy the SDK DLL to the output directory or to a directory in the system PATH.

    Other Visual Studio versions

    1. Follow the Visual Studio 2015 steps above to configure your project.

    2. Install the Visual C++ 2015 runtime (vc_redist.x64) on the target machine.

    Important

    To skip manual configuration, open the pre-configured demo project included in the SDK demo/ directory with Visual Studio 2015. Update the topic and access key values in the sample code, then build and run.

    What's next