Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[refactor] Modify the README to apply the new installation method #239

Merged
merged 4 commits into from Nov 27, 2022
Merged

[refactor] Modify the README to apply the new installation method #239

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a15fd80
[refactor] Modify the README to apply the new installation method
shibd Oct 31, 2022
c0ef4cc
Fix review.
shibd Nov 2, 2022
bedceba
format
shibd Nov 2, 2022
0caaae2
Move prebuilt binaries
shibd Nov 2, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
151 changes: 38 additions & 113 deletions README.md
View file
Open in desktop
Expand Up @@ -23,155 +23,80 @@

The Pulsar Node.js client can be used to create Pulsar producers and consumers in Node.js.

## Requirements

Pulsar Node.js client library is based on the C++ client library. Follow the instructions for
[C++ library](https://pulsar.apache.org/docs/en/client-libraries-cpp/) for installing the binaries through
[RPM](https://pulsar.apache.org/docs/en/client-libraries-cpp/#rpm),
[Deb](https://pulsar.apache.org/docs/en/client-libraries-cpp/#deb) or
[Homebrew packages](https://pulsar.apache.org/docs/en/client-libraries-cpp/#macos).

(Note: you will need to install not only the pulsar-client library but also the pulsar-client-dev library)

Also, this library works only in Node.js 10.x or later because it uses the
This library works only in Node.js 10.x or later because it uses the
[node-addon-api](https://github.com/nodejs/node-addon-api) module to wrap the C++ library.

## Compatibility

Compatibility between each version of the Node.js client and the C++ client is as follows:

| Node.js client | C++ client |
|----------------|-----------------|
| 1.0.x | 2.3.0 or later |
| 1.1.x | 2.4.0 or later |
| 1.2.x | 2.5.0 or later |
| 1.3.x | 2.7.0 or later |
| 1.4.x - 1.6.x | 2.8.0 or later |
| 1.7.x | 2.10.1 or later |

If an incompatible version of the C++ client is installed, you may fail to build or run this library.

## How to install

### Install on windows

1. Build the Pulsar C++ client on windows.

```shell
cmake \
-A x64 \
-DBUILD_PYTHON_WRAPPER=OFF -DBUILD_TESTS=OFF \
-DVCPKG_TRIPLET=x64-windows \
-DCMAKE_BUILD_TYPE=Release \
-S .
cmake --config Release
```

> **Note**
>
> These instructions are only available for versions after 1.8.0. For versions previous to 1.8.0, you need to install the C++ client first. Please switch to the corresponding version branch of this repo to read the specific instructions.

2. Set the variable `PULSAR_CPP_DIR` with the `pulsar-client-cpp` path in a Windows command tool.
### Use `npm`

```shell
# for example
set PULSAR_CPP_DIR=C:\pulsar\pulsar-client-cpp
npm install pulsar-client
```

3. Set the variable `OS_ARCH` in a Windows command tool, `OS_ARCH` is related to the configuration of VCPKG_TRIPLET on the command line above.(Optional)
### Use `yarn`

```shell
set OS_ARCH=x64-windows
yarn add pulsar-client
```

### Install on mac
After install, you can run the [examples](https://github.com/apache/pulsar-client-node/tree/master/examples).

1. Install the Pulsar C++ client on mac.
### Prebuilt binaries
shibd marked this conversation as resolved.
Show resolved Hide resolved

```shell
brew install libpulsar
```
The module uses [node-pre-gyp](https://github.com/mapbox/node-pre-gyp) to download the prebuilt binary for your platform, if it exists.
These binaries are hosted on ASF dist subversion. The following targets are currently provided:

2. Get the installation path of libpulsar
Format: `napi-{platform}-{libc}-{arch}`
- napi-darwin-unknown-x64.tar.gz
- napi-linux-glibc-arm64.tar.gz
- napi-linux-glibc-x64.tar.gz
- napi-linux-musl-arm64.tar.gz
- napi-linux-musl-x64.tar.gz
- napi-win32-unknown-ia32.tar.gz
- napi-win32-unknown-x64.tar.gz

```shell
brew info libpulsar
```
`darwin-arm64` systems are not currently supported, you can refer `How to build` to build from source.


2. Set the variable `PULSAR_CPP_DIR` with the `pulsar-client-cpp` path in a mac command tool.
## How to build

### 1. Clone repository.
```shell
# for example
## Intel x86_64
export PULSAR_CPP_DIR=/usr/local/Cellar/libpulsar/2.9.1_1

## Apple Silicon and Homebrew since 3.0.0
## cf. https://brew.sh/2021/02/05/homebrew-3.0.0/
export PULSAR_CPP_DIR=/opt/homebrew/Cellar/libpulsar/2.9.1_1
git clone https://github.com/apache/pulsar-client-node.git
cd pulsar-client-node
```

### Install on Linux
### 2. Install C++ client.

1. Require g++ and make commands to install pulsar-client
```
# rpm
$ yum install gcc-c++ make

# debian
$ apt-get install g++ make
```

2. Download rpm or debian packages.
```
# Set the version of Pulsar C++ client to install
$ PULSAR_CPP_CLIENT_VERSION=2.9.1
Select the appropriate installation method from below depending on your operating system:

# rpm
$ wget https://archive.apache.org/dist/pulsar/pulsar-${PULSAR_CPP_CLIENT_VERSION}/RPMS/apache-pulsar-client-${PULSAR_CPP_CLIENT_VERSION}-1.x86_64.rpm
$ wget https://archive.apache.org/dist/pulsar/pulsar-${PULSAR_CPP_CLIENT_VERSION}/RPMS/apache-pulsar-client-devel-${PULSAR_CPP_CLIENT_VERSION}-1.x86_64.rpm

# debian
$ wget https://archive.apache.org/dist/pulsar/pulsar-${PULSAR_CPP_CLIENT_VERSION}/DEB/apache-pulsar-client.deb
$ wget https://archive.apache.org/dist/pulsar/pulsar-${PULSAR_CPP_CLIENT_VERSION}/DEB/apache-pulsar-client-dev.deb
```

3. Install the Pulsar C++ client.
#### Install C++ client on macOS:
```shell
# rpm
$ rpm -ivh apache-pulsar-client*.rpm

# debian
$ apt install ./apache-pulsar-client*.deb
pkg/mac/build-cpp-deps-lib.sh
pkg/mac/build-cpp-lib.sh
```


### Install pulsar-client to your project

#### Install C++ client on Linux:
```shell
$ npm install pulsar-client
build-support/install-cpp-client.sh
```

## Sample code

Please refer to [examples](https://github.com/apache/pulsar-client-node/tree/master/examples).

## How to build

### Install dependent npm modules and build Pulsar client library:

#### Install C++ client on Windows (required preinstall `curl` and `7z`):
```shell
$ git clone https://github.com/apache/pulsar-client-node.git
$ cd pulsar-client-node
$ npm install
pkg\windows\download-cpp-client.bat
```

> **Note**
>
> If you build `pulsar-client-node on` windows, you need to set the variable `PULSAR_CPP_DIR` first, then install npm (run the command `npm install`) in a Windows command-line tool.

### Rebuild Pulsar client library:
### 3. Build NAPI from source

```shell
$ npm run build
npm install --build-from-source
```


## Documentation
* Please see https://pulsar.apache.org/docs/en/client-libraries-node for more details about the Pulsar Node.js client.
* Please see https://pulsar.apache.org/docs/client-libraries-node/ for more details about the Pulsar Node.js client.
5 changes: 4 additions & 1 deletion pkg/mac/common.sh
View file
Open in desktop
Expand Up @@ -19,7 +19,10 @@

set -e -x

export ARCH=${ARCH:-arm64}
if [ -z "$ARCH" ]; then
export ARCH=$(uname -m)
shibd marked this conversation as resolved.
Show resolved Hide resolved
fi

export MACOSX_DEPLOYMENT_TARGET=11.0

MAC_BUILD_DIR=`cd $(dirname $0); pwd`
Expand Down