Skip to content

Verify the candidate release in your local env

Jump to bottom
Yunze Xu edited this page Mar 25, 2024 · 6 revisions

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
  1. 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.

image

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

Screenshot 2023-11-21 at 19 42 24

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. For example,

./pulsar-test-service-start.sh
# This variable is the cmake build directory and will be used in run-unit-tests.sh later
export CMAKE_BUILD_DIRECTORY=build
cmake -B $CMAKE_BUILD_DIRECTORY -DINTEGRATE_VCPKG=ON -DBUILD_TESTS=ON -DBUILD_PERF_TOOLS=OFF
cmake --build $CMAKE_BUILD_DIRECTORY -j8
# It's important to disable the HTTPS proxy before testing. However, since there is a test that
# tries to access google.com, if your network environment cannot access Google, ignore that test
# by adding the --gtest_filter='-AuthPluginTest.testOauth2Failure' option to ./pulsar-tests in run-unit-tests.sh
export https_proxy=
./run-unit-tests.sh

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

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

The release manager should be responsible to open PRs in https://github.com/apache/pulsar-client-python and https://github.com/apache/pulsar-client-node to verify the tests will still pass in CI after upgrading the depended C++ client to the candidate release.

If some tests failed, please clarify the reason to ensure changes are reasonable but not simply regressions.

For those who verified the candidate release, they should verify that unit tests could pass in their local environments.

Verify 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.

Verify Pulsar Node.js client

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

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.

Clone this wiki locally