This topic describes the preparations, instructions, and precautions for using C++ SDK v1.x.x to access Message Queue for Apache RocketMQ, so that C++ SDK can be used to send and subscribe to messages.

Before using C++ SDK, pay attention to the following:

  • This topic is only for C++ SDK v1.x.x. If you want to use SDK v2.0.0, you can choose to Upgrade SDK v1.x.x to SDK v2.0.0 or download it. For more information about how to use SDK v2.0.0, see Prepare the environment (v2.0.0).
  • The topic and group ID in the code must have been created in the Message Queue for Apache RocketMQ console first. The message tag can be specified by application users. For more information about how to create a message tag, see Step 2: Create resources.
  • An application that uses Message Queue for Apache RocketMQ must have been deployed on an Elastic Compute Service (ECS) instance of Alibaba Cloud.

SDK download

C++ SDK supports the Windows and Linux operating systems with the same interface. CentOS 6 (RHEL 6) and CentOS 7 (RHEL 7) are supported on Linux. For more information about how to download the C++ SDK, see Release notes.

Download and decompress the package. The following directory structure is displayed:

  • demo/ (only for the Windows operating system)

    This directory contains a created Windows C++ demo.

  • example/

    This directory contains examples for sending and consuming normal messages and ordered messages and examples for sending messages in one-way mode. Besides, the package for Linux also contains a file Makefile for compiling and managing examples.

  • include/

    This directory contains header files required by your own programs.

  • lib/
    • The Linux SDK sub-directories are as follows, which are a 64-bit static library and a dynamic library respectively.
      lib-boost-share/
        libonsclient4cpp.so
      lib-boost-static/
        libonsclient4cpp.a                        
    • The Windows SDK sub-directory is as follows, which is a 64-bit SDK DLL library. If Visual Studio 2015 is not installed, install vc_redist.x64. This is the runtime environment for Visual C++ 2015.
      64/
      vc_redist.x64                        
  • SDK_GUIDE.pdf

    This file contains the SDK environment preparation document and FAQ.

  • changelog

    It contains a list of solved problems and newly added features in the new version.

Linux C++ SDK

From December 2, 2016, Linux C++ SDK added dependency on high performance Boost libraries (v1.62.0), which reduces the CPU resource usage and enhances the efficiency. Currently, it depends on boost_system, boost_thread, boost_chrono, and boost_filesystem libraries, including static and dynamic library solutions.

Static library solution

The Message Queue for Apache RocketMQ library file is in the lib/lib-boost-static directory and the Boost libraries are statically linked to libonsclient4cpp.a. Service providers who have no dependent Boost libraries can directly choose the static library solution. In the static library solution, the Boost libraries have been linked to libonsclient4cpp.a, and you just need to link to libonsclient4cpp.a when compiling the file. The code is as follows:

cd aliyun-mq-linux-cpp-sdk  //The path to which the downloaded SDK package is decompressed.
cd example                  //Go to the example directory and enter the relevant information such as the created topic and key in the example file.
make static=1            
Notice For completely static links, make sure that required static libraries such as libstdc++ and pthread have been installed on your machine. libstdc ++ that is installed by default does not contain static libraries. You need to run the yum or > apt-get command to install the static libraries.

The following warning message may be returned when you use the preceding method:

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

The best practice is to prevent completely static links, but to statically link to onsclient4cpp only and dynamically link to other libraries. The code is as follows:

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        

As GCC 5.x has introduced Dual ABI, you need to add the -D_GLIBCXX_USE_CXX11_ABI=0 option when compiling a link.

Dynamic library solution

The Message Queue for Apache RocketMQ library file is in the lib/lib-boost-share directory. When generating executable files, service providers need to link the Boost dynamic libraries to libonsclient4cpp.so. Since the service providers have depended on Boost libraries, in scenarios where the dynamic library solution is required, perform the following steps for the dependency of Boost libraries:

  1. Download Boost 1.62.0.

    boost 1.62.0

  2. Decompress the Boost 1.62.0 package.

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

  3. Install Boost 1.62.0.
    1. Run the cd path/to/boost_1_62_0 command to go to the directory extracted from the Boost 1.62.0 package.
    2. Run the ./bootstrap.sh command to configure Boost.
    3. Run the ./b2 link=shared runtime-link=shared command to compile Boost.
    4. Run the ./b2 install command to install Boost.
  4. Run the ldconfig -v|grep libboost command. If the system makes output, the Boost dynamic libraries are in the search paths of dynamic libraries.
  5. When executable files are generated, the Boost dynamic libraries must be linked to Message Queue for Apache RocketMQ dynamic libraries. The code is as follows:
    cd aliyun-mq-linux-cpp-sdk  //The path to which the downloaded SDK package is decompressed.
    cd example                  //Go to the example directory and enter the relevant information such as the topic and key created in the Message Queue for Apache RocketMQ console in the example file.
    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 C++ SDK in the Visual Studio 2015 environment

  1. Use Visual Studio 2015 to create your project.
  2. Right-click the project and choose Properties. In the window that appears, click Configuration Manager, and set Active solution configuration to Release and Active solution platform to x64.
  3. Right-click the project and choose Properties. In the window that appears, choose Configuration Properties > General, click Output Directory, and select /A. Based on the Active solution platform setting, copy all files in the 64-bit lib directory to the /A output directory.
  4. Right-click the project and choose Properties. In the window that appears, choose Configuration Properties > C/C++ > General, click Additional Include Directories, and select /B. Copy the header files in the include directory to the /B include directory.
  5. Right-click the project and choose Properties. In the window that appears, choose Configuration Properties > Linker > General, click Additional Library Directories, and select /A.
  6. Right-click the project and choose Properties. In the window that appears, choose Configuration Properties > Linker > Input, click Additional Dependencies, and select ONSClient4CPP.lib.
  7. Right-click the project and choose Properties. In the window that appears, choose Configuration Properties > C/C++ > General, click Preprocessor Definitions, and add the WIN32 macro.

Use C++ SDK in a non-Visual Studio 2015 environment

  1. Follow the preceding steps to configure your project based on the Visual Studio 2015 environment.
  2. Install vc_redist.x64. This is the runtime environment for Visual C++ 2015.
    Notice To prevent complex settings, you can use the preconfigured SDK demo. Download and decompress the SDK package, go to the demo directory, and open the project in Visual Studio 2015.

    The following figures show an example.

    Now, the compilation environment is ready. Click Build to compile an executable program. Then, copy the DLL file to the directory where the executable program resides to run the program. Alternatively, copy the DLL file to the system directory.

Upgrade SDK v1.x.x to SDK v2.0.0

Currently, SDK v2.0.0 is compatible with the APIs of SDK v1.x.x. Application Binary Interfaces (ABIs) are not compatible due to different implementation methods.

Perform the following steps:

  1. Replace the header files of the earlier version with those of the lastest SDK.
  2. Copy all the dynamic libraries in the lib directory of the new version to the directory that stores the dynamic libraries of the earlier version.
  3. If you are using a static library solution, remove the -static parameter to change to the default dynamic library solution.
  4. Add the -lrocketmq_client_core parameter to the compilation script to link to the kernel dynamic library of the new version.
  5. Recompile the project.
  6. If the upgrade fails, you can roll back the project to the pre-upgrade status and recompile it.

References