blob: 98c20f589838f58c1e52f05d2ad3302185f20818 [file] [log] [blame]
Nicolas Noble6ae8ef12015-01-16 15:03:42 -08001These instructions only cover building grpc C and C++ libraries under
2typical unix systems. If you need more information, please try grpc's
3wiki pages:
nnoble0005b772014-12-10 16:25:34 -08004
Nicolas Noble6ae8ef12015-01-16 15:03:42 -08005 https://github.com/google/grpc/wiki
nnoble0005b772014-12-10 16:25:34 -08006
Nicolas Noble6ae8ef12015-01-16 15:03:42 -08007
8*************************
9* If you are in a hurry *
10*************************
11
12A typical unix installation won't require any more steps than running:
13
14 $ make
15 # make install
16
17You don't need anything else than GNU Make and gcc. Under a Debian or
18Ubuntu system, this should boil down to the following package:
19
20 # apt-get install build-essential
21
22
23*******************************
24* More detailled instructions *
25*******************************
26
27Setting up dependencies
28=======================
29
30Dependencies to compile the libraries
31-------------------------------------
32
33grpc libraries have few external dependencies. If you need to compile and
34install them, they are present in the third_party directory if you have
35cloned the github repository recursively. If you didn't clone recursively,
36you can still get them later by running the following command:
37
38 $ git submodule update --init
nnoble0005b772014-12-10 16:25:34 -080039
nnoble69ac39f2014-12-12 15:43:38 -080040Note that the Makefile makes it much easier for you to compile from sources
Nicolas Noble6ae8ef12015-01-16 15:03:42 -080041if you were to clone recursively our git repository: it will automatically
42compile zlib and OpenSSL, which are core requirements for grpc. Note this
43creates grpc libraries that will have zlib and OpenSSL built-in inside of them,
44which significantly increases the libraries' size.
45
46In order to decrease that size, you can manually install zlib and OpenSSL on
47your system, so that the Makefile can use them instead.
48
49Under a Debian or Ubuntu system, one can acquire the development package
50for zlib this way:
51
52 # apt-get install zlib1g-dev
53
54To the best of our knowledge, no distribution has an OpenSSL package that
55supports ALPN yet, so you would still have to depend on installing from source
56for that particular dependency if you want to reduce the libraries' size.
57
58The recommended version of OpenSSL that provides ALPN support is available
59at this URL:
60
61 https://www.openssl.org/source/openssl-1.0.2-beta3.tar.gz
nnoble69ac39f2014-12-12 15:43:38 -080062
nnoble0005b772014-12-10 16:25:34 -080063
Nicolas Noble6ae8ef12015-01-16 15:03:42 -080064Dependencies to compile and run the tests
65-----------------------------------------
nnoble0005b772014-12-10 16:25:34 -080066
Nicolas Noble6ae8ef12015-01-16 15:03:42 -080067Compiling and running grpc plain-C tests dont't require any more dependency.
nnoble0005b772014-12-10 16:25:34 -080068
Nicolas Noble6ae8ef12015-01-16 15:03:42 -080069
70Compiling and running grpc C++ tests depend on protobuf 3.0.0, gtest and
71gflags. Although gflags and protobuf are provided in third_party, you will
72need to manually install these dependencies on your system to run these tests.
73
74Under a Debian or Ubuntu system, you can install the gtests and gflags packages
75using apt-get:
76
77 # apt-get install libgflags-dev libgtest-dev
78
79However, protobuf 3.0.0 isn't in a debian package yet: you'll need to compile
80and install it from the sources in the third_party. Note that if you already
81have the protobuf and protoc packages installed on your system, they will most
82likely interfere, and you'll need to uninstall them first.
83
84Compiling and installing protobuf 3.0.0 requires a few more dependencies in
85itself, notably the autoconf suite, curl, and unzip. If you have apt-get, you
86can install these dependencies this way:
87
88 # apt-get install unzip curl autotools-dev
89
90Then, you can build and install protobuf 3.0.0:
91
92 $ cd third_party/protobuf
93 $ ./configure
94 $ make
95 # make install
96 # ldconfig
97
98
99A word on OpenSSL
100-----------------
nnoble0005b772014-12-10 16:25:34 -0800101
102Secure HTTP2 requires to have the TLS extension ALPN (see rfc 7301 and
103http://http2.github.io/http2-spec/ section 3.3). Our HTTP2 implementation
104relies on OpenSSL's implementation. OpenSSL 1.0.2beta3 is the first version
105of OpenSSL that has ALPN support, and this explains our dependency on it.
106
nnoble69ac39f2014-12-12 15:43:38 -0800107Note that the Makefile supports compiling only the unsecure elements of grpc,
108and if you do not have OpenSSL and do not want it, you can still proceed
109with installing only the elements you require. However, it is recommended
110to encrypt your network traffic, therefore we urge you to not use the unsecure
111version of grpc if possible.
112
nnoble0005b772014-12-10 16:25:34 -0800113
114Compiling
115=========
116
Nicolas Noble6ae8ef12015-01-16 15:03:42 -0800117If you have all the dependencies mentioned above, you should simply be able
118to go ahead and run "make" to compile grpc's C and C++ libraries:
nnoble0005b772014-12-10 16:25:34 -0800119
Nicolas Noble6ae8ef12015-01-16 15:03:42 -0800120 $ make
nnoble0005b772014-12-10 16:25:34 -0800121
122
123Testing
124=======
125
Nicolas Noble6ae8ef12015-01-16 15:03:42 -0800126To build and run the tests, you can run the command:
nnoble0005b772014-12-10 16:25:34 -0800127
Nicolas Noble6ae8ef12015-01-16 15:03:42 -0800128 $ make test
129
130If you want to be able to run them in parallel, and get better output, you can
131also use the python tool we have written:
132
133 $ ./tools/run_tests/run_tests.py
nnoble0005b772014-12-10 16:25:34 -0800134
135
136Installing
137==========
138
Nicolas Noble6ae8ef12015-01-16 15:03:42 -0800139Once everything is compiled, you should be able to install grpc C and C++
nnoble0005b772014-12-10 16:25:34 -0800140libraries and headers:
141
Nicolas Noble6ae8ef12015-01-16 15:03:42 -0800142 # make install