getting_started.md 12.5 KB
Newer Older
1
# BUILD
2

gejun's avatar
gejun committed
3
brpc prefers static linkages of deps, so that they don't have to be installed on every machine running the app.
4

5 6
brpc depends on following packages:

7 8 9
* [gflags](https://github.com/gflags/gflags): Extensively used to define global options.
* [protobuf](https://github.com/google/protobuf): Serializations of messages, interfaces of services.
* [leveldb](https://github.com/google/leveldb): Required by [/rpcz](rpcz.md) to record RPCs for tracing.
10

zhujiashun's avatar
zhujiashun committed
11
# Supported Environment
zhujiashun's avatar
zhujiashun committed
12

zhujiashun's avatar
zhujiashun committed
13 14
* [Ubuntu/LinuxMint/WSL](#ubuntulinuxmintwsl)
* [Fedora/CentOS](#fedoracentos)
zhujiashun's avatar
zhujiashun committed
15 16 17
* [Linux with self-built deps](#linux-with-self-built-deps)
* [MacOS](#macos)

18
## Ubuntu/LinuxMint/WSL
19 20
### Prepare deps

21
Install common deps:
Ge Jun's avatar
Ge Jun committed
22
```shell
23
sudo apt-get install git g++ make libssl-dev
24 25
```

26
Install [gflags](https://github.com/gflags/gflags), [protobuf](https://github.com/google/protobuf), [leveldb](https://github.com/google/leveldb):
Ge Jun's avatar
Ge Jun committed
27
```shell
28
sudo apt-get install libgflags-dev libprotobuf-dev libprotoc-dev protobuf-compiler libleveldb-dev
29 30
```

31
If you need to statically link leveldb:
Ge Jun's avatar
Ge Jun committed
32
```shell
33
sudo apt-get install libsnappy-dev
34
```
35

Ge Jun's avatar
Ge Jun committed
36 37
If you need to enable cpu/heap profilers in examples:
```shell
38
sudo apt-get install libgoogle-perftools-dev
Ge Jun's avatar
Ge Jun committed
39 40
```

41 42
If you need to run tests, install and compile libgtest-dev (which is not compiled yet):
```shell
43
sudo apt-get install libgtest-dev && cd /usr/src/gtest && sudo cmake . && sudo make && sudo mv libgtest* /usr/lib/ && cd -
44 45 46
```
The directory of gtest source code may be changed, try `/usr/src/googletest/googletest` if `/usr/src/gtest` is not there.

47
### Compile brpc with config_brpc.sh
48
git clone brpc, cd into the repo and run
Ge Jun's avatar
Ge Jun committed
49
```shell
50
$ sh config_brpc.sh --headers=/usr/include --libs=/usr/lib
51
$ make
52
```
53 54 55
To change compiler to clang, add `--cxx=clang++ --cc=clang`.

To not link debugging symbols, add `--nodebugsymbols` and compiled binaries will be much smaller.
56

Ge Jun's avatar
Ge Jun committed
57 58
To use brpc with glog, add `--with-glog`.

gejun's avatar
gejun committed
59
To enable [thrift support](../en/thrift.md), install thrift first and add `--with-thrift`.
Ge Jun's avatar
Ge Jun committed
60

61
**Run example**
62

Ge Jun's avatar
Ge Jun committed
63
```shell
64 65 66 67
$ cd example/echo_c++
$ make
$ ./echo_server &
$ ./echo_client
68
```
69

70
Examples link brpc statically, if you need to link the shared version, `make clean` and `LINK_SO=1 make`
71

72
**Run tests**
gejun's avatar
gejun committed
73
```shell
74 75 76
$ cd test
$ make
$ sh run_tests.sh
gejun's avatar
gejun committed
77 78
```

79
### Compile brpc with cmake
Ge Jun's avatar
Ge Jun committed
80
```shell
81
mkdir bld && cd bld && cmake .. && make
82 83 84
```
To change compiler to clang, overwrite environment variable CC and CXX to clang and clang++.

85
To not link debugging symbols, use `cmake -DWITH_DEBUG_SYMBOLS=OFF ..` and compiled binaries will be much smaller.
86

Ge Jun's avatar
Ge Jun committed
87 88
To use brpc with glog, add `-DWITH_GLOG=ON`.

gejun's avatar
gejun committed
89
To enable [thrift support](../en/thrift.md), install thrift first and add `-DWITH_THRIFT=ON`.
Ge Jun's avatar
Ge Jun committed
90

91
**Run example with cmake**
Ge Jun's avatar
Ge Jun committed
92
```shell
93
$ cd example/echo_c++
94
$ mkdir bld && cd bld && cmake .. && make
95 96 97 98 99 100
$ ./echo_server &
$ ./echo_client
```
Examples link brpc statically, if you need to link the shared version, use `cmake -DEXAMPLE_LINK_SO=ON ..`

**Run tests**
Ge Jun's avatar
Ge Jun committed
101
```shell
102
$ mkdir bld && cd bld && cmake -DBUILD_UNIT_TESTS=ON .. && make
103 104
$ cd test
$ sh run_tests.sh
105 106
```

107 108 109 110
## Fedora/CentOS

### Prepare deps

111
CentOS needs to install EPEL generally otherwise many packages are not available by default.
Ge Jun's avatar
Ge Jun committed
112
```shell
113
sudo yum install epel-release
114 115
```

116
Install common deps:
Ge Jun's avatar
Ge Jun committed
117
```shell
118
sudo yum install git gcc-c++ make openssl-devel
119
```
120

121
Install [gflags](https://github.com/gflags/gflags), [protobuf](https://github.com/google/protobuf), [leveldb](https://github.com/google/leveldb):
Ge Jun's avatar
Ge Jun committed
122
```shell
123
sudo yum install gflags-devel protobuf-devel protobuf-compiler leveldb-devel
124
```
Ge Jun's avatar
Ge Jun committed
125 126 127

If you need to enable cpu/heap profilers in examples:
```shell
128
sudo yum install gperftools-devel
129
```
Ge Jun's avatar
Ge Jun committed
130

131 132
If you need to run tests, install and compile gtest-devel (which is not compiled yet):
```shell
133
sudo yum install gtest-devel
134 135
```

136
### Compile brpc with config_brpc.sh
137

138
git clone brpc, cd into the repo and run
139

Ge Jun's avatar
Ge Jun committed
140
```shell
141 142 143
$ sh config_brpc.sh --headers=/usr/include --libs=/usr/lib64
$ make
```
144 145 146
To change compiler to clang, add `--cxx=clang++ --cc=clang`.

To not link debugging symbols, add `--nodebugsymbols` and compiled binaries will be much smaller.
147

Ge Jun's avatar
Ge Jun committed
148 149
To use brpc with glog, add `--with-glog`.

gejun's avatar
gejun committed
150
To enable [thrift support](../en/thrift.md), install thrift first and add `--with-thrift`.
Ge Jun's avatar
Ge Jun committed
151

152
**Run example**
153

Ge Jun's avatar
Ge Jun committed
154
```shell
155 156 157 158 159
$ cd example/echo_c++
$ make
$ ./echo_server &
$ ./echo_client
```
160

161 162
Examples link brpc statically, if you need to link the shared version, `make clean` and `LINK_SO=1 make`

163
**Run tests**
164 165 166 167 168
```shell
$ cd test
$ make
$ sh run_tests.sh
```
169 170

### Compile brpc with cmake
Ge Jun's avatar
Ge Jun committed
171
```shell
172
mkdir bld && cd bld && cmake .. && make
173 174 175
```
To change compiler to clang, overwrite environment variable CC and CXX to clang and clang++.

176
To not link debugging symbols, use `cmake -DWITH_DEBUG_SYMBOLS=OFF ..` and compiled binaries will be much smaller.
177

Ge Jun's avatar
Ge Jun committed
178 179
To use brpc with glog, add `-DWITH_GLOG=ON`.

gejun's avatar
gejun committed
180
To enable [thrift support](../en/thrift.md), install thrift first and add `-DWITH_THRIFT=ON`.
Ge Jun's avatar
Ge Jun committed
181

182 183
**Run example**

Ge Jun's avatar
Ge Jun committed
184
```shell
185
$ cd example/echo_c++
186
$ mkdir bld && cd bld && cmake .. && make
187 188 189 190 191
$ ./echo_server &
$ ./echo_client
```
Examples link brpc statically, if you need to link the shared version, use `cmake -DEXAMPLE_LINK_SO=ON ..`

192
**Run tests**
Ge Jun's avatar
Ge Jun committed
193
```shell
194
$ mkdir bld && cd bld && cmake -DBUILD_UNIT_TESTS=ON .. && make
195 196
$ cd test
$ sh run_tests.sh
197 198
```

199 200 201 202 203 204
## Linux with self-built deps

### Prepare deps

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.

205
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:
Ge Jun's avatar
Ge Jun committed
206 207 208
```shell
$ cmake . -DBUILD_SHARED_LIBS=1 -DBUILD_STATIC_LIBS=1
$ make
209
```
210 211 212

### Compile brpc

213
Keep on with the gflags example, let `../gflags_dev` be where gflags is cloned.
214 215 216

git clone brpc. cd into the repo and run

Ge Jun's avatar
Ge Jun committed
217
```shell
218 219 220 221
$ sh config_brpc.sh --headers="../gflags_dev /usr/include" --libs="../gflags_dev /usr/lib64"
$ make
```

Ge Jun's avatar
Ge Jun committed
222 223
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.

224 225 226
To change compiler to clang, add `--cxx=clang++ --cc=clang`.

To not link debugging symbols, add `--nodebugsymbols` and compiled binaries will be much smaller.
227

Ge Jun's avatar
Ge Jun committed
228
To use brpc with glog, add `--with-glog`.
229

gejun's avatar
gejun committed
230
To enable [thrift support](../en/thrift.md), install thrift first and add `--with-thrift`.
Ge Jun's avatar
Ge Jun committed
231 232

```shell
233 234 235 236 237 238
$ ls my_dev
gflags_dev protobuf_dev leveldb_dev brpc_dev
$ cd brpc_dev
$ sh config_brpc.sh --headers=.. --libs=..
$ make
```
239

240 241 242 243
### Compile brpc with cmake

git clone brpc. cd into the repo and run

Ge Jun's avatar
Ge Jun committed
244
```shell
245
mkdir bld && cd bld && cmake -DCMAKE_INCLUDE_PATH="/path/to/dep1/include;/path/to/dep2/include" -DCMAKE_LIBRARY_PATH="/path/to/dep1/lib;/path/to/dep2/lib" .. && make
246 247 248 249
```

To change compiler to clang, overwrite environment variable CC and CXX to clang and clang++.

250
To not link debugging symbols, use `cmake -DWITH_DEBUG_SYMBOLS=OFF ..` and compiled binaries will be much smaller.
251

Ge Jun's avatar
Ge Jun committed
252 253
To use brpc with glog, add `-DWITH_GLOG=ON`.

gejun's avatar
gejun committed
254
To enable [thrift support](../en/thrift.md), install thrift first and add `-DWITH_THRIFT=ON`.
Ge Jun's avatar
Ge Jun committed
255

zhujiashun's avatar
zhujiashun committed
256
## MacOS
257 258 259

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.

zhujiashun's avatar
zhujiashun committed
260 261 262
### Prepare deps

Install common deps:
Ge Jun's avatar
Ge Jun committed
263
```shell
264
brew install openssl git gnu-getopt coreutils
zhujiashun's avatar
zhujiashun committed
265 266 267
```

Install [gflags](https://github.com/gflags/gflags), [protobuf](https://github.com/google/protobuf), [leveldb](https://github.com/google/leveldb):
Ge Jun's avatar
Ge Jun committed
268
```shell
269
brew install gflags protobuf leveldb
zhujiashun's avatar
zhujiashun committed
270 271
```

Ge Jun's avatar
Ge Jun committed
272 273
If you need to enable cpu/heap profilers in examples:
```shell
274
brew install gperftools
275 276 277 278
```

If you need to run tests, install and compile googletest (which is not compiled yet):
```shell
279
git clone https://github.com/google/googletest && cd googletest/googletest && mkdir bld && cd bld && cmake .. && make && sudo mv libgtest* /usr/lib/ && cd -
Ge Jun's avatar
Ge Jun committed
280 281
```

zhujiashun's avatar
zhujiashun committed
282 283
### Compile brpc with config_brpc.sh
git clone brpc, cd into the repo and run
Ge Jun's avatar
Ge Jun committed
284
```shell
zhujiashun's avatar
zhujiashun committed
285
$ sh config_brpc.sh --headers=/usr/local/include --libs=/usr/local/lib --cc=clang --cxx=clang++
zhujiashun's avatar
zhujiashun committed
286 287 288 289
$ make
```
To not link debugging symbols, add `--nodebugsymbols` and compiled binaries will be much smaller.

Ge Jun's avatar
Ge Jun committed
290 291
To use brpc with glog, add `--with-glog`.

gejun's avatar
gejun committed
292
To enable [thrift support](../en/thrift.md), install thrift first and add `--with-thrift`.
Ge Jun's avatar
Ge Jun committed
293

zhujiashun's avatar
zhujiashun committed
294 295
**Run example**

Ge Jun's avatar
Ge Jun committed
296
```shell
zhujiashun's avatar
zhujiashun committed
297 298 299 300 301 302 303 304 305 306
$ cd example/echo_c++
$ make
$ ./echo_server &
$ ./echo_client
```

Examples link brpc statically, if you need to link the shared version, `make clean` and `LINK_SO=1 make`

**Run tests**
```shell
307 308 309
$ cd test
$ make
$ sh run_tests.sh
zhujiashun's avatar
zhujiashun committed
310 311 312
```

### Compile brpc with cmake
Ge Jun's avatar
Ge Jun committed
313
```shell
314
mkdir bld && cd bld && cmake .. && make
zhujiashun's avatar
zhujiashun committed
315 316 317 318
```

To not link debugging symbols, use `cmake -DWITH_DEBUG_SYMBOLS=OFF ..` and compiled binaries will be much smaller.

Ge Jun's avatar
Ge Jun committed
319 320
To use brpc with glog, add `-DWITH_GLOG=ON`.

gejun's avatar
gejun committed
321
To enable [thrift support](../en/thrift.md), install thrift first and add `-DWITH_THRIFT=ON`.
Ge Jun's avatar
Ge Jun committed
322

zhujiashun's avatar
zhujiashun committed
323
**Run example with cmake**
Ge Jun's avatar
Ge Jun committed
324
```shell
zhujiashun's avatar
zhujiashun committed
325
$ cd example/echo_c++
326
$ mkdir bld && cd bld && cmake .. && make
zhujiashun's avatar
zhujiashun committed
327 328 329 330 331 332
$ ./echo_server &
$ ./echo_client
```
Examples link brpc statically, if you need to link the shared version, use `cmake -DEXAMPLE_LINK_SO=ON ..`

**Run tests**
Ge Jun's avatar
Ge Jun committed
333
```shell
334
$ mkdir bld && cd bld && cmake -DBUILD_UNIT_TESTS=ON .. && make
335 336
$ cd test
$ sh run_tests.sh
zhujiashun's avatar
zhujiashun committed
337 338
```

339
# Supported deps
340

341
## GCC: 4.8-7.1
342

gejun's avatar
gejun committed
343
c++11 is turned on by default to remove dependencies on boost (atomic).
344

345
The over-aligned issues in GCC7 is suppressed temporarily now.
346

347
Using other versions of gcc may generate warnings, contact us to fix.
348

gejun's avatar
gejun committed
349
Adding `-D__const__=` to cxxflags in your makefiles is a must to avoid [errno issue in gcc4+](thread_local.md).
350

gejun's avatar
gejun committed
351
## Clang: 3.5-4.0
352

gejun's avatar
gejun committed
353
no known issues.
354

gejun's avatar
gejun committed
355
## glibc: 2.12-2.25
356

357
no known issues.
358

359
## protobuf: 2.4-3.4
360

361
Be compatible with pb 3.x and pb 2.x with the same file:
362
Don't use new types in proto3 and start the proto file with `syntax="proto2";`
gejun's avatar
gejun committed
363
[tools/add_syntax_equal_proto2_to_all.sh](https://github.com/brpc/brpc/blob/master/tools/add_syntax_equal_proto2_to_all.sh)can add `syntax="proto2"` to all proto files without it.
gejun's avatar
gejun committed
364 365

Arena in pb 3.x is not supported yet.
366

367
## gflags: 2.0-2.21
368

369
no known issues.
370

gejun's avatar
gejun committed
371
## openssl: 0.97-1.1
372

373
required by https.
374

gejun's avatar
gejun committed
375
## tcmalloc: 1.7-2.5
376

gejun's avatar
gejun committed
377
brpc does **not** link [tcmalloc](http://goog-perftools.sourceforge.net/doc/tcmalloc.html) by default. Users link tcmalloc on-demand.
378

gejun's avatar
gejun committed
379
Comparing to ptmalloc embedded in glibc, tcmalloc often improves performance. However different versions of tcmalloc may behave really differently. For example, tcmalloc 2.1 may make multi-threaded examples in brpc perform significantly worse(due to a spinlock in tcmalloc) than the one using tcmalloc 1.7 and 2.5. Even different minor versions may differ. When you program behave unexpectedly, remove tcmalloc or try another version.
380

gejun's avatar
gejun committed
381
Code compiled with gcc 4.8.2 and linked to a tcmalloc compiled with earlier GCC may crash or deadlock before main(), E.g:
382

gejun's avatar
gejun committed
383
![img](../images/tcmalloc_stuck.png)
384

gejun's avatar
gejun committed
385
When you meet the issue, compile tcmalloc with the same GCC.
386

387
Another common issue with tcmalloc is that it does not return memory to system as early as ptmalloc. So when there's an invalid memory access, the program may not crash directly, instead it crashes at a unrelated place, or even not crash. When you program has weird memory issues, try removing tcmalloc.
388

gejun's avatar
gejun committed
389
If you want to use [cpu profiler](cpu_profiler.md) or [heap profiler](heap_profiler.md), do link `libtcmalloc_and_profiler.a`. These two profilers are based on tcmalloc.[contention profiler](contention_profiler.md) does not require tcmalloc.
390

gejun's avatar
gejun committed
391
When you remove tcmalloc, not only remove the linkage with tcmalloc but also the macro `-DBRPC_ENABLE_CPU_PROFILER`.
392

393 394
## glog: 3.3+

wangxuefeng's avatar
wangxuefeng committed
395
brpc implements a default [logging utility](../../src/butil/logging.h) which conflicts with glog. To replace this with glog, add *--with-glog* to config_brpc.sh or add `-DWITH_GLOG=ON` to cmake.
396

397
## valgrind: 3.8+
398

399
brpc detects valgrind automatically (and registers stacks of bthread). Older valgrind(say 3.2) is not supported.
400

Ge Jun's avatar
Ge Jun committed
401 402 403 404
## thrift: 0.9.3-0.11.0

no known issues.

gejun's avatar
gejun committed
405
# Track instances
406

gejun's avatar
gejun committed
407
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.