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

Download the SDK

The C++ SDK offers an identical API for Windows and Linux. Supported Linux distributions include CentOS 6 (RHEL 6) and CentOS 7 (RHEL 7). To download the C++ SDK, see Release notes for the TCP client SDK for C++.

After you download and extract the package, you will see the following directory structure:

• demo/ (For Windows only)

  A pre-built Windows C++ demo project.

• example/

  Examples for sending normal messages, one-way messages, and ordered messages, and for consuming normal and ordered messages. On Linux, this directory also contains a Makefile to compile and manage the example files.

• include/

  The header files required for your application.

• lib/

  • The subdirectories for the Linux SDK contain the 64-bit static library and dynamic library.

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

  • The subdirectory for the Windows SDK contains the 64-bit DLL. If you do not have Visual Studio 2015 installed, you must install vc_redist.x64. This is the runtime for Visual C++ 2015.

    64/
    vc_redist.x64                        

• SDK_GUIDE.pdf

  Documentation and FAQs for setting up the SDK environment.

• changelog

  A list of bug fixes and new features in new releases.

Linux C++ SDK

Since December 2, 2016, the Linux C++ SDK has depended on the high-performance Boost library (version 1.62.0) to reduce CPU usage and improve efficiency. It primarily depends on four libraries: boost_system, boost_thread, boost_chrono, and boost_filesystem. Both static and dynamic linking solutions are available.

Static linking

The library files for ApsaraMQ for RocketMQ are in the lib/lib-boost-static directory, where the Boost library is statically linked to libonsclient4cpp.a. If your application does not have a dependency on the Boost library, you can directly use this static library solution. In this solution, the Boost library is already linked to libonsclient4cpp.a, so you only need to link against libonsclient4cpp.a during compilation. No other operations are required. The usage is as follows.

cd aliyun-mq-linux-cpp-sdk  // The directory where you extracted the SDK.
cd example                  // Enter the example directory and modify the example file with your topic, key, and other information.
make static=1            

Using this method 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            

As a best practice, we recommend avoiding a fully static link. Instead, statically link only onsclient4cpp and dynamically link other libraries. Use the following command:

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        

Additionally, because GCC 5.x introduces a Dual ABI, add the -D_GLIBCXX_USE_CXX11_ABI=0 option when you compile and link.

Dynamic linking

The ApsaraMQ for RocketMQ library files are in the lib/lib-boost-share directory. You must link the Boost dynamic libraries and libonsclient4cpp.so when you generate your executable file. If your application already depends on Boost and you need to use the dynamic linking solution, perform the following steps:

1. Download Boost version 1.62.0.

   boost 1.62.0

2. Extract the Boost 1.62.0 package.

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

3. Install Boost 1.62.0.

   1. Change to the directory where you extracted Boost 1.62.0: 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. Run ldconfig -v|grep libboost. Any output from this command confirms that the Boost dynamic libraries are in the dynamic library search path.

5. When you generate the executable file, link the Boost dynamic libraries and the ApsaraMQ for RocketMQ dynamic library by using the following commands:

   cd aliyun-mq-linux-cpp-sdk  // The directory where you extracted the SDK.
   cd example                  // Enter the example directory and modify the example file with your topic, key, and other information from the ApsaraMQ for 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 the search path for dynamic loading.
   ./a.out  // Run the program.

Windows C++ SDK

Use the C++ SDK in a Visual Studio 2015 environment

1. Create a new project in Visual Studio 2015. In the New Project dialog, expand Installed > Templates > Visual C++, select Win32, and then choose Win32 Console Application. After you set a project name, click OK. On the Win32 Application Wizard overview page, confirm that the project type is Console application and click Next >. On the Application Settings page, set Application type to Console application, select the Empty project checkbox, and then click Finish.

2. Right-click your project in the Solution Explorer and select Properties > Configuration Manager. Set Active solution configuration to release and Active solution platform to x64.

3. Right-click the project, select Properties > Configuration Properties > General, and set Output Directory to /A. Based on the Active solution platform setting, copy all files from the 64-bit lib directory to the output directory /A. Right-click the project, select Properties > Configuration Properties > General, confirm that the Output Directory is $(SolutionDir)$(Platform)\$(Configuration)\ (this path is automatically generated after the build), and set Platform Toolset to Visual Studio 2015 - Windows XP (v140_xp). Copy the ONSClient4CPP.dll, ONSClient4CPP.lib, and ONSClient4CPP.pdb files from the lib directory of the downloaded SDK into this output directory.

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

5. Right-click the project and select Properties > Configuration Properties > Linker > General > Additional Library Directories: /A. Add the path to the lib directory of the SDK, such as E:\aliyun-mq-windows-cpp-sdk\lib\64, which contains the relevant DLL files. If you use Visual Studio 2015 on Windows 7, you must also add the ucrt library path, such as C:\Program Files (x86)\Windows Kits\10\Lib\10.0.10150.0\ucrt\x64.

6. Navigate to Properties > Configuration Properties > Linker > Input. Add ONSClient4CPP.lib to Additional Dependencies.

7. Navigate to Properties > Configuration Properties > C/C++ > Preprocessor. Add the WIN32 macro to Preprocessor Definitions.

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

1. First, configure your project by following the steps for the Visual Studio 2015 environment.

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

   Important

   To avoid manual configuration, 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.

   In Solution Explorer, right-click the demo project and open its properties. Set Configuration to Release and Platform to x64. Expand Configuration Properties > C/C++ > General. Edit the Additional Include Directories field and add two paths: ../../include and C:\Program Files (x86)\Windows Kits\10\Include\10.0.10150.0\ucrt. Replace the version number, such as 10.0.10150.0, with the version of Windows Kits installed on your machine.

   Your build environment is now configured. Click Build to compile the executable program. To run the program, copy the DLL file to the same directory as the executable or to a system directory.

More information

Sample code