All Products
Search

This Product

    ApsaraMQ for RocketMQ:Prepare the environment (v1.x.x)

    Document Center

    ApsaraMQ for RocketMQ:Prepare the environment (v1.x.x)

    Last Updated:Aug 03, 2026

    This topic describes how to prepare the environment for using the C++ SDK v1.x.x to connect to Message Queue for Apache RocketMQ. This allows you to use the SDK to send and receive messages.

    Before you begin:

    • This topic only applies to C++ SDK v1.x.x.

    • In the console, create the topics and group IDs that your code will use. You can customize message tags in your application. For more information about how to create resources, see Create resources.

    • Applications that use Message Queue for Apache RocketMQ must be deployed on ECS instances.

    Download Tablestore SDK for C++

    The C++ SDK supports Windows and Linux operating systems with identical interfaces. The CentOS 6(RHEL 6) and CentOS 7(RHEL 7) series are supported in Linux. For more information about how to download the C++ SDK, see Release notes for the TCP client SDK for C++.

    After the download is complete, decompress the package. The directory structure is as follows:

    • demo/(for Windows only)

      Contains a created Windows C++ demo.

    • example/

      Examples include normal message sending, one-way message sending, ordered message sending, normal message consumption, and ordered message consumption. Linux also includes Makefile for example compilation and management.

    • include/

      This directory contains header files required by your own programs.

    • lib/

      • The following subdirectories of the Linux SDK are the static and dynamic libraries of 64. 

        lib-boost-share/
  libonsclient4cpp.so
lib-boost-static/
  libonsclient4cpp.a

      • The Windows SDK subdirectory is as follows, which is the dll library of the SDK in a 64-bit system. If no Visual Studio 2015 environment is installed, copy the installation vc_redist.x64. This is the run time environment for Visual C++ 2015. 

        64/
vc_redist.x64

    • SDK_GUIDE.pdf

      Contains the documentation and frequently asked questions (FAQ) about how to prepare the SDK environment.

    • changelog

      Contains bug fixes and new features in the new releases.

    Linux C++ SDK

    Since December 02, 2016, the Linux CPP version relies on the high-performance boost library (version 1.62.0), which not only reduces the CPU resource utilization rate, but also improves the operation efficiency. Currently, it mainly relies on four libraries: boost_system, boost_thread, boost_chrono, and boost_filesystem. There are two solutions: static library and dynamic library.

    Static Solution

    The ApsaraMQ for RocketMQ library file is in the lib/lib-boost-static directory. The boost library is statically linked to the libonsclient4cpp.a. For business parties that do not rely on the boost library, you can directly select the static library solution. In the static library solution, the corresponding boost library has been linked to the libonsclient4cpp.a. You only need to link the libonsclient4cpp.a during compilation, and no other operations are required. The following code provides an example on how to set the fields: 

    cd aliyun-mq-linux-cpp-sdk // The path where the downloaded SDK is decompressed.
cd example // Go to the example directory, modify the example file, and enter the information about the topic and key that you created.
make static=1
    Important

    For full static links, make sure that libstdc++, pthread and other related static libraries are installed on the machine. By default, libstdc++ does not have static libraries installed, so you need to install related static libraries through yum or apt-get.

    In addition, some warning messages will appear as follows when using the above method. 

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

    It is recommended that the best way is not to use complete static links, but only to statically link onsclient4cpp, and other libraries can be dynamically linked. The following code provides an example on how to set the fields: 

    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

    In addition, because GCC 5.x introduces Dual ABI, when compiling links, add -D_GLIBCXX_USE_CXX11_ABI=0 compiler options.

    Dynamic solutions

    The ApsaraMQ for RocketMQ library file is in the lib/lib-boost-share directory, and the business side needs to link the boost dynamic library and libonsclient4cpp.so when generating the executable file. if the business side has already relied on the boost library and needs to select a dynamic library solution, the following work needs to be done to rely on the boost library:

    1. Download Boost 1.62.0.

      boost 1.62.0

    2. Decompress boost 1.62.0.

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

    3. Install boost version 1.62.0:

      1. Go to the path after boost 1.62.0 decompression: cd path/to/boost_1_62_0

      2. Configure boost: ./bootstrap.sh

      3. Compile boost: ./b2 link=shared runtime-link=shared

      4. Install boost: ./b2 install

    4. The execution ldconfig -v|grep libboost. If there is relevant output, it indicates that the boost dynamic library is in the dynamic library search path.

    5. When generating an executable file, you need to link the boost dynamic library and the ApsaraMQ for RocketMQ dynamic library. The method is as follows. 

      cd aliyun-mq-linux-cpp-sdk // The path where the downloaded SDK is decompressed.
cd example // Go to the example directory, modify the example file, and enter the topics and keys that you created in the Message Queue for Apache RocketMQ console.
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/"  //Add dynamically loaded search paths.
./a.out  //Run the program.

    Windows C++ SDK

    Use the C++ SDK in Visual Studio 2015

    1. Create a project in Visual Studio 2015.

      Click New Project. In the New Project dialog box, select Installed > Templates > Visual C++ > Win32, then select Win32 Console Application and click OK to create the project.

      In the Win32 Application Wizard dialog box, confirm that the project type is Console application, then click Next to proceed to the next configuration step.

      Set Application type to Console application, select Empty project, then click Finish to create an empty project.

    2. Right-click the project and select Property > Configuration Manager. Set Active solution configuration to release and Active solution platform to x64.

    3. Right-click the project and navigate to Property > Configuration Properties > General. Set Output Directory to /A. Based on the Active solution platform setting, copy all files from the 64-bit lib directory into the output directory /A.

      Set Platform Toolset to Visual Studio 2015 - Windows XP (v140_xp). The Output Directory value is $(SolutionDir)$(Platform)\$(Configuration)\, which is generated automatically after the build. Copy ONSClient4CPP.dll, ONSClient4CPP.lib, and ONSClient4CPP.pdb from the SDK's lib directory to this build output directory.

    4. Right-click the project and navigate to Property > Configuration Properties > C/C++ > General. Set Additional Include Directories to /B. Copy the header files from the include directory into /B.

      Add the SDK's include directory path (for example, E:\aliyun-mq-windows-cpp-sdk\include). Alternatively, specify another directory and copy the SDK include files to it. If you are using VS2015 on Windows 7, also add the Windows Kits ucrt path, for example, C:\Program Files (x86)\Windows Kits\10\Include\10.0.10150.0\ucrt.

    5. Right-click the project and navigate to Property > Configuration Properties > Linker > General. Set Additional Library Directories to /A.

      Add the following paths:

      • The SDK's lib\64 directory path (contains the relevant DLL files).

      • If you use VS2015 on Windows 7, also add the Windows Kits ucrt\x64 path, for example, C:\Program Files (x86)\Windows Kits\10\Lib\10.0.10150.0\ucrt\x64.

    6. Right-click the project and navigate to Property > Configuration Properties > Linker > Input. Set Additional Dependencies to ONSClient4CPP.lib.

    7. Right-click the project and navigate to Property > Configuration Properties > C/C++ > Preprocessor. Add the WIN32 macro to Preprocessor Definitions.

      Set Preprocessor Definitions to NDEBUG;WIN32_CONSOLE;%(PreprocessorDefinitions).

    Use the C++ SDK in an environment other than Visual Studio 2015

    1. Configure your environment by following the steps in the "Use the C++ SDK in Visual Studio 2015" section.

    2. Install vc_redist.x64, the runtime for Visual C++ 2015.

      Important

      To avoid complex configurations, you can use the pre-configured SDK demo. After you download and extract the SDK, go to the demo directory and open the project in Visual Studio 2015.

      1. In Solution Explorer, right-click the demo project and select Properties to open the properties page.

      2. Expand Configuration Properties > C/C++ > General.

      3. Edit Additional Include Directories and add the paths ../../include and C:\Program Files (x86)\Windows Kits\10\Include\10.0.10150.0\ucrt.

      4. Replace the version number in the ucrt path (such as 10.0.10150.0) with the version of the Windows SDK installed on your machine.

      Click Build to compile the project. To run the executable, copy the required DLLs to the executable's directory or to a system directory.

    Related topics