Verify the candidate release in your local env

Verify the candidate release

Generally, the release candidate for version X.Y.Z has the following artifacts:

apache-pulsar-client-cpp-X.Y.Z.tar.gz  -- The source code
apk-arm64/aarch64/*.apk                -- The Alpine Linux packages for arm64 architecture
apk-x86_64/x86_64/*.apk                -- The Alpine Linux packages for x86_64 architecture
deb-arm64/*.deb                        -- The Debian packages for arm64 architecture
deb-x86_64/*.deb                       -- The Debian packages for x86_64 architecture
rpm-arm64/aarch64/*.rpm                -- The RPM packages for arm64 architecture
rpm-x86_64/x86_64/*.rpm                -- The RPM packages for x86_64 architecture
x64-windows-static.tar.gz              -- The Windows x64 artifacts
x86-windows-static.tar.gz              -- The Windows x86 artifacts
macos-arm64.zip                        -- The macOS artifacts for arm64 architecture (since 3.4.1)
macos-x86_64.zip                       -- The macOS artifacts for x86_64 architecture (since 3.4.1)

How to build from source

See https://github.com/apache/pulsar-client-cpp#compilation

How to use the pre-built binaries

For Windows and Linux users, there is a 3rd-party project that can help verify it: https://github.com/BewareMyPower/pulsar-client-cpp-demo

Linux users

See https://pulsar.apache.org/docs/3.1.x/client-libraries-cpp-setup/ for how to install a pre-built binaries from the source and https://pulsar.apache.org/docs/3.1.x/client-libraries-cpp/#changes-for-300-and-later-versions for how to build an application via GCC.

Windows users

See https://github.com/BewareMyPower/pulsar-client-cpp-demo/tree/main/windows#readme

macOS users

Use a clean directory and unzip the file:

unzip macos-arm64.zip # Use arm64 as an example

Then you will see the following directories:

include/pulsar/*.h  -- C/C++ Headers
lib/*.a             -- static libraries
lib/*.dylib         -- dynamic library

Given a code example named main.cc, you can build the application in two ways.

1. Link to the static library:

clang++ main.cc ./lib/libpulsarwithdeps.a -std=c++11 -I./include
./a.out

2. Link to the dynamic library:

clang++ main.cc -std=c++11 -I./include -L./lib -Wl,-rpath ./lib -lpulsar

Note: when you link to the dynamic library, the macOS might tell you the libpulsar.dylib is a malicious software.

Go to System Settings - Privacy & Security - Security, click the Allow Anyway button.

Then you can run the binary ./a.out.

Run unit tests

See https://github.com/apache/pulsar-client-cpp#tests

There are also some individual tests, see https://github.com/apache/pulsar-client-cpp/blob/main/run-unit-tests.sh for more details.

Code example

There are some code examples in https://github.com/apache/pulsar-client-cpp/tree/main/examples but they all include an internal header LogUtils.h. You can either copy that header into your project directory or remove the related code. e.g. SampleConsumer.cc can be modified to:

#include <pulsar/Client.h>

#include <iostream>

using namespace pulsar;

int main() {
    Client client("pulsar://localhost:6650");

    Consumer consumer;
    Result result = client.subscribe("persistent://public/default/my-topic", "consumer-1", consumer);
    if (result != ResultOk) {
        std::cerr << "Failed to subscribe: " << result << std::endl;
        return -1;
    }

    Message msg;

    while (true) {
        consumer.receive(msg);
        std::cout << "Received: " << msg << "  with payload '" << msg.getDataAsString() << "'" << std::endl;

        consumer.acknowledge(msg);
    }

    client.close();
}

You can also test your own code example.

Verify the 3rd party projects that depend on Pulsar C++ client

Pulsar Python client

Example: https://github.com/apache/pulsar-client-python/pull/164

You need to modify:

1. build-support/dep-url.sh, which specifies where to download the source code of the C++ client.
2. dependencies.yaml, which specifies the version.

Then you can open a PR (in your own fork), which will run the unit tests and build the Python wheels.

Pulsar Node.js client

Example: https://github.com/shibd/pulsar-client-node/pull/36

You need to modify the CPP_CLIENT_BASE_URL and CPP_CLIENT_VERSION in pulsar-client-cpp.txt.

Breaking Changes

If there are some tests failed and you think the change does not make sense, feel free left your concern in the VOTE email. For example, changing the error code from ConnectError to AuthenticationError when client does not configure authentication correctly is might be acceptable.