Skip to content

B
brpc
Commit 38eacc9f authored by Ge Jun's avatar Ge Jun
Browse files
Options

polish getting_started.md

parent 943c7736
Hide whitespace changes
Inline Side-by-side
Showing with 86 additions and 40 deletions
docs/cn/getting_started.md
View file @ 38eacc9f
...@@ -19,23 +19,28 @@ brpc depends on following packages: ...@@ -19,23 +19,28 @@ brpc depends on following packages:
### Prepare deps ### Prepare deps
Install common deps: Install common deps:
``` ```shell
$ sudo apt-get install git g++ make libssl-dev $ sudo apt-get install git g++ make libssl-dev
``` ```
Install [gflags](https://github.com/gflags/gflags), [protobuf](https://github.com/google/protobuf), [leveldb](https://github.com/google/leveldb): Install [gflags](https://github.com/gflags/gflags), [protobuf](https://github.com/google/protobuf), [leveldb](https://github.com/google/leveldb):
``` ```shell
$ sudo apt-get install libgflags-dev libprotobuf-dev libprotoc-dev protobuf-compiler libleveldb-dev $ sudo apt-get install libgflags-dev libprotobuf-dev libprotoc-dev protobuf-compiler libleveldb-dev
``` ```
If you need to statically link leveldb: If you need to statically link leveldb:
``` ```shell
$ sudo apt-get install libsnappy-dev $ sudo apt-get install libsnappy-dev
``` ```
If you need to enable cpu/heap profilers in examples:
```shell
$ sudo apt-get install libgoogle-perftools-dev
```
### Compile brpc with config_brpc.sh ### Compile brpc with config_brpc.sh
git clone brpc, cd into the repo and run git clone brpc, cd into the repo and run
``` ```shell
$ sh config_brpc.sh --headers=/usr/include --libs=/usr/lib $ sh config_brpc.sh --headers=/usr/include --libs=/usr/lib
$ make $ make
``` ```
...@@ -43,9 +48,13 @@ To change compiler to clang, add `--cxx=clang++ --cc=clang`. ...@@ -43,9 +48,13 @@ To change compiler to clang, add `--cxx=clang++ --cc=clang`.
To not link debugging symbols, add `--nodebugsymbols` and compiled binaries will be much smaller. To not link debugging symbols, add `--nodebugsymbols` and compiled binaries will be much smaller.
To use brpc with glog, add `--with-glog`.
To enable thrift support, install thrift first and add `--with-thrift`.
**Run example** **Run example**
``` ```shell
$ cd example/echo_c++ $ cd example/echo_c++
$ make $ make
$ ./echo_server & $ ./echo_server &
...@@ -54,14 +63,12 @@ $ ./echo_client ...@@ -54,14 +63,12 @@ $ ./echo_client
Examples link brpc statically, if you need to link the shared version, `make clean` and `LINK_SO=1 make` Examples link brpc statically, if you need to link the shared version, `make clean` and `LINK_SO=1 make`
To run examples with cpu/heap profilers, install `libgoogle-perftools-dev` and re-run `config_brpc.sh` before compiling.
**Run tests** **Run tests**
Install and compile libgtest-dev (which is not compiled yet): Install and compile libgtest-dev (which is not compiled yet):
```shell ```shell
sudo apt-get install libgtest-dev && cd /usr/src/gtest && sudo cmake . && sudo make && sudo mv libgtest* /usr/lib/ && cd - $ sudo apt-get install libgtest-dev && cd /usr/src/gtest && sudo cmake . && sudo make && sudo mv libgtest* /usr/lib/ && cd -
``` ```
The directory of gtest source code may be changed, try `/usr/src/googletest/googletest` if `/usr/src/gtest` is not there. The directory of gtest source code may be changed, try `/usr/src/googletest/googletest` if `/usr/src/gtest` is not there.
...@@ -69,15 +76,19 @@ The directory of gtest source code may be changed, try `/usr/src/googletest/goog ...@@ -69,15 +76,19 @@ The directory of gtest source code may be changed, try `/usr/src/googletest/goog
Rerun `config_brpc.sh`, `make` in test/, and `sh run_tests.sh` Rerun `config_brpc.sh`, `make` in test/, and `sh run_tests.sh`
### Compile brpc with cmake ### Compile brpc with cmake
``` ```shell
$ mkdir build && cd build && cmake .. && make $ mkdir build && cd build && cmake .. && make
``` ```
To change compiler to clang, overwrite environment variable CC and CXX to clang and clang++. To change compiler to clang, overwrite environment variable CC and CXX to clang and clang++.
To not link debugging symbols, use `cmake -DWITH_DEBUG_SYMBOLS=OFF ..` and compiled binaries will be much smaller. To not link debugging symbols, use `cmake -DWITH_DEBUG_SYMBOLS=OFF ..` and compiled binaries will be much smaller.
To use brpc with glog, add `-DWITH_GLOG=ON`.
To enable thrift support, install thrift first and add `-DWITH_THRIFT=ON`.
**Run example with cmake** **Run example with cmake**
``` ```shell
$ cd example/echo_c++ $ cd example/echo_c++
$ mkdir build && cd build && cmake .. && make $ mkdir build && cd build && cmake .. && make
$ ./echo_server & $ ./echo_server &
...@@ -89,7 +100,7 @@ Examples link brpc statically, if you need to link the shared version, use `cmak ...@@ -89,7 +100,7 @@ Examples link brpc statically, if you need to link the shared version, use `cmak
Install gtest like just written above. Install gtest like just written above.
``` ```shell
$ mkdir build && cd build && cmake -DBUILD_UNIT_TESTS=ON .. && make $ mkdir build && cd build && cmake -DBUILD_UNIT_TESTS=ON .. && make
$ cd test && sh run_tests.sh $ cd test && sh run_tests.sh
``` ```
...@@ -99,24 +110,30 @@ $ cd test && sh run_tests.sh ...@@ -99,24 +110,30 @@ $ cd test && sh run_tests.sh
### Prepare deps ### Prepare deps
CentOS needs to install EPEL generally otherwise many packages are not available by default. CentOS needs to install EPEL generally otherwise many packages are not available by default.
``` ```shell
sudo yum install epel-release $ sudo yum install epel-release
``` ```
Install common deps: Install common deps:
``` ```shell
sudo yum install git gcc-c++ make openssl-devel $ sudo yum install git gcc-c++ make openssl-devel
``` ```
Install [gflags](https://github.com/gflags/gflags), [protobuf](https://github.com/google/protobuf), [leveldb](https://github.com/google/leveldb): Install [gflags](https://github.com/gflags/gflags), [protobuf](https://github.com/google/protobuf), [leveldb](https://github.com/google/leveldb):
```shell
$ sudo yum install gflags-devel protobuf-devel protobuf-compiler leveldb-devel
``` ```
sudo yum install gflags-devel protobuf-devel protobuf-compiler leveldb-devel
If you need to enable cpu/heap profilers in examples:
```shell
$ sudo yum install gperftools-devel
``` ```
### Compile brpc with config_brpc.sh ### Compile brpc with config_brpc.sh
git clone brpc, cd into the repo and run git clone brpc, cd into the repo and run
``` ```shell
$ sh config_brpc.sh --headers=/usr/include --libs=/usr/lib64 $ sh config_brpc.sh --headers=/usr/include --libs=/usr/lib64
$ make $ make
``` ```
...@@ -124,9 +141,13 @@ To change compiler to clang, add `--cxx=clang++ --cc=clang`. ...@@ -124,9 +141,13 @@ To change compiler to clang, add `--cxx=clang++ --cc=clang`.
To not link debugging symbols, add `--nodebugsymbols` and compiled binaries will be much smaller. To not link debugging symbols, add `--nodebugsymbols` and compiled binaries will be much smaller.
To use brpc with glog, add `--with-glog`.
To enable thrift support, install thrift first and add `--with-thrift`.
**Run example** **Run example**
``` ```shell
$ cd example/echo_c++ $ cd example/echo_c++
$ make $ make
$ ./echo_server & $ ./echo_server &
...@@ -135,8 +156,6 @@ $ ./echo_client ...@@ -135,8 +156,6 @@ $ ./echo_client
Examples link brpc statically, if you need to link the shared version, `make clean` and `LINK_SO=1 make` Examples link brpc statically, if you need to link the shared version, `make clean` and `LINK_SO=1 make`
To run examples with cpu/heap profilers, install `gperftools-devel` and re-run `config_brpc.sh` before compiling.
**Run tests** **Run tests**
Install gtest-devel. Install gtest-devel.
...@@ -144,16 +163,20 @@ Install gtest-devel. ...@@ -144,16 +163,20 @@ Install gtest-devel.
Rerun `config_brpc.sh`, `make` in test/, and `sh run_tests.sh` Rerun `config_brpc.sh`, `make` in test/, and `sh run_tests.sh`
### Compile brpc with cmake ### Compile brpc with cmake
``` ```shell
$ mkdir build && cd build && cmake .. && make $ mkdir build && cd build && cmake .. && make
``` ```
To change compiler to clang, overwrite environment variable CC and CXX to clang and clang++. To change compiler to clang, overwrite environment variable CC and CXX to clang and clang++.
To not link debugging symbols, use `cmake -DWITH_DEBUG_SYMBOLS=OFF ..` and compiled binaries will be much smaller. To not link debugging symbols, use `cmake -DWITH_DEBUG_SYMBOLS=OFF ..` and compiled binaries will be much smaller.
To use brpc with glog, add `-DWITH_GLOG=ON`.
To enable thrift support, install thrift first and add `-DWITH_THRIFT=ON`.
**Run example** **Run example**
``` ```shell
$ cd example/echo_c++ $ cd example/echo_c++
$ mkdir build && cd build && cmake .. && make $ mkdir build && cd build && cmake .. && make
$ ./echo_server & $ ./echo_server &
...@@ -163,7 +186,7 @@ Examples link brpc statically, if you need to link the shared version, use `cmak ...@@ -163,7 +186,7 @@ Examples link brpc statically, if you need to link the shared version, use `cmak
**Run tests** **Run tests**
``` ```shell
$ mkdir build && cd build && cmake -DBUILD_UNIT_TESTS=ON .. && make $ mkdir build && cd build && cmake -DBUILD_UNIT_TESTS=ON .. && make
$ cd test && sh run_tests.sh $ cd test && sh run_tests.sh
``` ```
...@@ -175,9 +198,9 @@ $ cd test && sh run_tests.sh ...@@ -175,9 +198,9 @@ $ cd test && sh run_tests.sh
brpc builds itself to both static and shared libs by default, so it needs static and shared libs of deps to be built as well. brpc builds itself to both static and shared libs by default, so it needs static and shared libs of deps to be built as well.
Take [gflags](https://github.com/gflags/gflags) as example, which does not build shared lib by default, you need to pass options to `cmake` to change the behavior: Take [gflags](https://github.com/gflags/gflags) as example, which does not build shared lib by default, you need to pass options to `cmake` to change the behavior:
``` ```shell
cmake . -DBUILD_SHARED_LIBS=1 -DBUILD_STATIC_LIBS=1 $ cmake . -DBUILD_SHARED_LIBS=1 -DBUILD_STATIC_LIBS=1
make $ make
``` ```
### Compile brpc ### Compile brpc
...@@ -186,18 +209,22 @@ Keep on with the gflags example, let `../gflags_dev` be where gflags is cloned. ...@@ -186,18 +209,22 @@ Keep on with the gflags example, let `../gflags_dev` be where gflags is cloned.
git clone brpc. cd into the repo and run git clone brpc. cd into the repo and run
``` ```shell
$ sh config_brpc.sh --headers="../gflags_dev /usr/include" --libs="../gflags_dev /usr/lib64" $ sh config_brpc.sh --headers="../gflags_dev /usr/include" --libs="../gflags_dev /usr/lib64"
$ make $ make
``` ```
Here we pass multiple paths to `--headers` and `--libs` to make the script search for multiple places. You can also group all deps and brpc into one directory, then pass the directory to --headers/--libs which actually search all subdirectories recursively and will find necessary files.
To change compiler to clang, add `--cxx=clang++ --cc=clang`. To change compiler to clang, add `--cxx=clang++ --cc=clang`.
To not link debugging symbols, add `--nodebugsymbols` and compiled binaries will be much smaller. To not link debugging symbols, add `--nodebugsymbols` and compiled binaries will be much smaller.
Here we pass multiple paths to `--headers` and `--libs` to make the script search for multiple places. You can also group all deps and brpc into one directory, then pass the directory to --headers/--libs which actually search all subdirectories recursively and will find necessary files. To use brpc with glog, add `--with-glog`.
``` To enable thrift support, install thrift first and add `--with-thrift`.
```shell
$ ls my_dev $ ls my_dev
gflags_dev protobuf_dev leveldb_dev brpc_dev gflags_dev protobuf_dev leveldb_dev brpc_dev
$ cd brpc_dev $ cd brpc_dev
...@@ -209,7 +236,7 @@ $ make ...@@ -209,7 +236,7 @@ $ make
git clone brpc. cd into the repo and run git clone brpc. cd into the repo and run
``` ```shell
$ mkdir build && cd build && cmake -DCMAKE_INCLUDE_PATH="/path/to/dep1/include;/path/to/dep2/include" -DCMAKE_LIBRARY_PATH="/path/to/dep1/lib;/path/to/dep2/lib" .. && make $ mkdir build && cd build && cmake -DCMAKE_INCLUDE_PATH="/path/to/dep1/include;/path/to/dep2/include" -DCMAKE_LIBRARY_PATH="/path/to/dep1/lib;/path/to/dep2/lib" .. && make
``` ```
...@@ -217,6 +244,10 @@ To change compiler to clang, overwrite environment variable CC and CXX to clang ...@@ -217,6 +244,10 @@ To change compiler to clang, overwrite environment variable CC and CXX to clang
To not link debugging symbols, use `cmake -DWITH_DEBUG_SYMBOLS=OFF ..` and compiled binaries will be much smaller. To not link debugging symbols, use `cmake -DWITH_DEBUG_SYMBOLS=OFF ..` and compiled binaries will be much smaller.
To use brpc with glog, add `-DWITH_GLOG=ON`.
To enable thrift support, install thrift first and add `-DWITH_THRIFT=ON`.
## MacOS ## MacOS
Note: In the same running environment, the performance of the current Mac version is about 2.5 times worse than the Linux version. If your service is performance-critical, do not use MacOS as your production environment. Note: In the same running environment, the performance of the current Mac version is about 2.5 times worse than the Linux version. If your service is performance-critical, do not use MacOS as your production environment.
...@@ -224,26 +255,35 @@ Note: In the same running environment, the performance of the current Mac versio ...@@ -224,26 +255,35 @@ Note: In the same running environment, the performance of the current Mac versio
### Prepare deps ### Prepare deps
Install common deps: Install common deps:
``` ```shell
$ brew install openssl git gnu-getopt coreutils $ brew install openssl git gnu-getopt coreutils
``` ```
Install [gflags](https://github.com/gflags/gflags), [protobuf](https://github.com/google/protobuf), [leveldb](https://github.com/google/leveldb): Install [gflags](https://github.com/gflags/gflags), [protobuf](https://github.com/google/protobuf), [leveldb](https://github.com/google/leveldb):
``` ```shell
$ brew install gflags protobuf leveldb $ brew install gflags protobuf leveldb
``` ```
If you need to enable cpu/heap profilers in examples:
```shell
$ brew install google-perftools
```
### Compile brpc with config_brpc.sh ### Compile brpc with config_brpc.sh
git clone brpc, cd into the repo and run git clone brpc, cd into the repo and run
``` ```shell
$ sh config_brpc.sh --headers=/usr/local/include --libs=/usr/local/lib --cc=clang --cxx=clang++ $ sh config_brpc.sh --headers=/usr/local/include --libs=/usr/local/lib --cc=clang --cxx=clang++
$ make $ make
``` ```
To not link debugging symbols, add `--nodebugsymbols` and compiled binaries will be much smaller. To not link debugging symbols, add `--nodebugsymbols` and compiled binaries will be much smaller.
To use brpc with glog, add `--with-glog`.
To enable thrift support, install thrift first and add `--with-thrift`.
**Run example** **Run example**
``` ```shell
$ cd example/echo_c++ $ cd example/echo_c++
$ make $ make
$ ./echo_server & $ ./echo_server &
...@@ -252,27 +292,29 @@ $ ./echo_client ...@@ -252,27 +292,29 @@ $ ./echo_client
Examples link brpc statically, if you need to link the shared version, `make clean` and `LINK_SO=1 make` Examples link brpc statically, if you need to link the shared version, `make clean` and `LINK_SO=1 make`
To run examples with cpu/heap profilers, install `gperftools` and re-run `config_brpc.sh` before compiling.
**Run tests** **Run tests**
Install and compile googletest (which is not compiled yet): Install and compile googletest (which is not compiled yet):
```shell ```shell
git clone https://github.com/google/googletest && cd googletest/googletest && mkdir build && cd build && cmake .. && make && sudo mv libgtest* /usr/lib/ && cd - $ git clone https://github.com/google/googletest && cd googletest/googletest && mkdir build && cd build && cmake .. && make && sudo mv libgtest* /usr/lib/ && cd -
``` ```
Rerun `config_brpc.sh`, `make` in test/, and `sh run_tests.sh` Rerun `config_brpc.sh`, `make` in test/, and `sh run_tests.sh`
### Compile brpc with cmake ### Compile brpc with cmake
``` ```shell
$ mkdir build && cd build && cmake .. && make $ mkdir build && cd build && cmake .. && make
``` ```
To not link debugging symbols, use `cmake -DWITH_DEBUG_SYMBOLS=OFF ..` and compiled binaries will be much smaller. To not link debugging symbols, use `cmake -DWITH_DEBUG_SYMBOLS=OFF ..` and compiled binaries will be much smaller.
To use brpc with glog, add `-DWITH_GLOG=ON`.
To enable thrift support, install thrift first and add `-DWITH_THRIFT=ON`.
**Run example with cmake** **Run example with cmake**
``` ```shell
$ cd example/echo_c++ $ cd example/echo_c++
$ mkdir build && cd build && cmake .. && make $ mkdir build && cd build && cmake .. && make
$ ./echo_server & $ ./echo_server &
...@@ -284,7 +326,7 @@ Examples link brpc statically, if you need to link the shared version, use `cmak ...@@ -284,7 +326,7 @@ Examples link brpc statically, if you need to link the shared version, use `cmak
Install gtest like just written above. Install gtest like just written above.
``` ```shell
$ mkdir build && cd build && cmake -DBUILD_UNIT_TESTS=ON .. && make $ mkdir build && cd build && cmake -DBUILD_UNIT_TESTS=ON .. && make
$ cd test && sh run_tests.sh $ cd test && sh run_tests.sh
``` ```
...@@ -351,6 +393,10 @@ brpc implements a default [logging utility](../../src/butil/logging.h) which con ...@@ -351,6 +393,10 @@ brpc implements a default [logging utility](../../src/butil/logging.h) which con
brpc detects valgrind automatically (and registers stacks of bthread). Older valgrind(say 3.2) is not supported. brpc detects valgrind automatically (and registers stacks of bthread). Older valgrind(say 3.2) is not supported.
## thrift: 0.9.3-0.11.0
no known issues.
# Track instances # Track instances
We provide a program to help you to track and monitor all brpc instances. Just run [trackme_server](https://github.com/brpc/brpc/tree/master/tools/trackme_server/) somewhere and launch need-to-be-tracked instances with -trackme_server=SERVER. The trackme_server will receive pings from instances periodically and print logs when it does. You can aggregate instance addresses from the log and call builtin services of the instances for further information. We provide a program to help you to track and monitor all brpc instances. Just run [trackme_server](https://github.com/brpc/brpc/tree/master/tools/trackme_server/) somewhere and launch need-to-be-tracked instances with -trackme_server=SERVER. The trackme_server will receive pings from instances periodically and print logs when it does. You can aggregate instance addresses from the log and call builtin services of the instances for further information.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment