blob: 50040d7d21cc4f7d8bdc5bf42508b89d686a3a59 [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
Dan Cirulide3c6542015-02-25 12:50:09 -080012 $ git clone https://github.com/grpc/grpc.git
Dan Ciruli4175d842015-02-25 16:24:22 -080013 $ cd grpc
Dan Cirulide3c6542015-02-25 12:50:09 -080014 $ git submodule update --init
Dan Ciruli4175d842015-02-25 16:24:22 -080015 $ make
16 $ sudo make install
Nicolas Noble6ae8ef12015-01-16 15:03:42 -080017
Nicolas Noblec70752a2015-02-12 17:01:52 -080018You don't need anything else than GNU Make, gcc and autotools. Under a Debian
19or Ubuntu system, this should boil down to the following packages:
Nicolas Noble6ae8ef12015-01-16 15:03:42 -080020
Dan Cirulide3c6542015-02-25 12:50:09 -080021 $ apt-get install build-essential autoconf libtool
Nicolas Noblec70752a2015-02-12 17:01:52 -080022
23Building the python wrapper requires the following:
24
25 # apt-get install python-all-dev python-virtualenv
Nicolas Noble6ae8ef12015-01-16 15:03:42 -080026
Nicolas "Pixel" Noble522d7122015-02-19 01:28:02 +010027If you want to install in a different directory than the default /usr/lib, you can
28override it on the command line:
29
30 # make install prefix=/opt
31
Nicolas Noble6ae8ef12015-01-16 15:03:42 -080032
33*******************************
34* More detailled instructions *
35*******************************
36
37Setting up dependencies
38=======================
39
40Dependencies to compile the libraries
41-------------------------------------
42
43grpc libraries have few external dependencies. If you need to compile and
44install them, they are present in the third_party directory if you have
45cloned the github repository recursively. If you didn't clone recursively,
46you can still get them later by running the following command:
47
48 $ git submodule update --init
nnoble0005b772014-12-10 16:25:34 -080049
nnoble69ac39f2014-12-12 15:43:38 -080050Note that the Makefile makes it much easier for you to compile from sources
Nicolas Noble6ae8ef12015-01-16 15:03:42 -080051if you were to clone recursively our git repository: it will automatically
52compile zlib and OpenSSL, which are core requirements for grpc. Note this
53creates grpc libraries that will have zlib and OpenSSL built-in inside of them,
54which significantly increases the libraries' size.
55
56In order to decrease that size, you can manually install zlib and OpenSSL on
57your system, so that the Makefile can use them instead.
58
59Under a Debian or Ubuntu system, one can acquire the development package
60for zlib this way:
61
62 # apt-get install zlib1g-dev
63
64To the best of our knowledge, no distribution has an OpenSSL package that
65supports ALPN yet, so you would still have to depend on installing from source
66for that particular dependency if you want to reduce the libraries' size.
67
68The recommended version of OpenSSL that provides ALPN support is available
69at this URL:
70
Nicolas "Pixel" Nobled5660212015-01-23 20:35:49 +010071 https://www.openssl.org/source/openssl-1.0.2.tar.gz
nnoble69ac39f2014-12-12 15:43:38 -080072
nnoble0005b772014-12-10 16:25:34 -080073
Nicolas Noble6ae8ef12015-01-16 15:03:42 -080074Dependencies to compile and run the tests
75-----------------------------------------
nnoble0005b772014-12-10 16:25:34 -080076
Nicolas Noble6ae8ef12015-01-16 15:03:42 -080077Compiling and running grpc plain-C tests dont't require any more dependency.
nnoble0005b772014-12-10 16:25:34 -080078
Nicolas Noble6ae8ef12015-01-16 15:03:42 -080079
80Compiling and running grpc C++ tests depend on protobuf 3.0.0, gtest and
Nicolas Noblec70752a2015-02-12 17:01:52 -080081gflags. Although gflags is provided in third_party, you will need to manually
82install that dependency on your system to run these tests.
Nicolas Noble6ae8ef12015-01-16 15:03:42 -080083
84Under a Debian or Ubuntu system, you can install the gtests and gflags packages
85using apt-get:
86
87 # apt-get install libgflags-dev libgtest-dev
88
Nicolas Noblec70752a2015-02-12 17:01:52 -080089However, protobuf 3.0.0 isn't in a debian package yet, but the Makefile will
90automatically try and compile the one present in third_party if you cloned the
91repository recursively, and that it detects your system is lacking it.
Nicolas Noble6ae8ef12015-01-16 15:03:42 -080092
93Compiling and installing protobuf 3.0.0 requires a few more dependencies in
Nicolas Noblec70752a2015-02-12 17:01:52 -080094itself, notably the autoconf suite. If you have apt-get, you can install
95these dependencies this way:
Nicolas Noble6ae8ef12015-01-16 15:03:42 -080096
Nicolas Noblec70752a2015-02-12 17:01:52 -080097 # apt-get install autoconf libtool
Nicolas Noble6ae8ef12015-01-16 15:03:42 -080098
Nicolas "Pixel" Nobled66cba22015-02-14 02:59:12 +010099If you want to run the tests using one of the sanitized configurations, you
100will need clang and its instrumented libc++:
101
102 # apt-get install clang libc++-dev
103
vjpai7cc2c302015-02-18 12:33:37 -0800104Mac-specific notes:
105-------------------
106
107For a Mac system, git is not available by default. You will first need to
108install Xcode from the Mac AppStore and then run the following command from a
109terminal:
110
111 $ sudo xcode-select --install
112
113You should also install "port" following the instructions at
114https://www.macports.org . This will reside in /opt/local/bin/port for
115most Mac installations. Do the "git submodule" command listed above.
116
117Then execute the following for all the needed build dependencies
118
119 $ sudo /opt/local/bin/port install autoconf automake libtool gflags cmake
120 $ mkdir ~/gtest
121 $ svn checkout http://googletest.googlecode.com/svn/trunk/ gtest-svn
122 $ mkdir mybuild
123 $ cd mybuild
124 $ cmake ../gtest-svn
125 $ make
126 $ make gtest.a gtest_main.a
127 $ sudo cp libgtest.a libgtest_main.a /opt/local/lib
128 $ sudo mkdir /opt/local/include/gtest
129 $ sudo cp -pr ../gtest-svn/include/gtest /opt/local/include/gtest
130
131We will also need to make openssl and install it appropriately
132
133 $ cd <git directory>
134 $ cd third_party/openssl
135 $ sudo make install
136 $ cd ../../
137
138If you are going to make changes and need to regenerate the projects file,
139you will need to install certain modules for python.
140
141 $ sudo easy_install simplejson mako
Nicolas Noble6ae8ef12015-01-16 15:03:42 -0800142
143A word on OpenSSL
144-----------------
nnoble0005b772014-12-10 16:25:34 -0800145
Abhishek Kumar3dd9df92015-02-10 10:16:41 -0800146Secure HTTP2 requires the TLS extension ALPN (see rfc 7301 and
nnoble0005b772014-12-10 16:25:34 -0800147http://http2.github.io/http2-spec/ section 3.3). Our HTTP2 implementation
Nicolas "Pixel" Nobled5660212015-01-23 20:35:49 +0100148relies on OpenSSL's implementation. OpenSSL 1.0.2 is the first released version
nnoble0005b772014-12-10 16:25:34 -0800149of OpenSSL that has ALPN support, and this explains our dependency on it.
150
nnoble69ac39f2014-12-12 15:43:38 -0800151Note that the Makefile supports compiling only the unsecure elements of grpc,
152and if you do not have OpenSSL and do not want it, you can still proceed
Abhishek Kumar6749e732015-02-10 10:59:52 -0800153with installing only the elements you require. However, we strongly recommend
Abhishek Kumar3dd9df92015-02-10 10:16:41 -0800154the use of encryption for all network traffic, and discourage the use of grpc
155without TLS.
nnoble69ac39f2014-12-12 15:43:38 -0800156
nnoble0005b772014-12-10 16:25:34 -0800157
158Compiling
159=========
160
Nicolas Noble6ae8ef12015-01-16 15:03:42 -0800161If you have all the dependencies mentioned above, you should simply be able
162to go ahead and run "make" to compile grpc's C and C++ libraries:
nnoble0005b772014-12-10 16:25:34 -0800163
Nicolas Noble6ae8ef12015-01-16 15:03:42 -0800164 $ make
nnoble0005b772014-12-10 16:25:34 -0800165
166
167Testing
168=======
169
Nicolas Noble6ae8ef12015-01-16 15:03:42 -0800170To build and run the tests, you can run the command:
nnoble0005b772014-12-10 16:25:34 -0800171
Nicolas Noble6ae8ef12015-01-16 15:03:42 -0800172 $ make test
173
174If you want to be able to run them in parallel, and get better output, you can
175also use the python tool we have written:
176
177 $ ./tools/run_tests/run_tests.py
nnoble0005b772014-12-10 16:25:34 -0800178
179
180Installing
181==========
182
Nicolas Noble6ae8ef12015-01-16 15:03:42 -0800183Once everything is compiled, you should be able to install grpc C and C++
nnoble0005b772014-12-10 16:25:34 -0800184libraries and headers:
185
Nicolas Noble6ae8ef12015-01-16 15:03:42 -0800186 # make install