Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 1 | These instructions only cover building grpc C and C++ libraries under |
| 2 | typical unix systems. If you need more information, please try grpc's |
| 3 | wiki pages: |
nnoble | 0005b77 | 2014-12-10 16:25:34 -0800 | [diff] [blame] | 4 | |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 5 | https://github.com/google/grpc/wiki |
nnoble | 0005b77 | 2014-12-10 16:25:34 -0800 | [diff] [blame] | 6 | |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 7 | |
| 8 | ************************* |
| 9 | * If you are in a hurry * |
| 10 | ************************* |
| 11 | |
Stanley Cheung | a79a896 | 2015-08-19 10:43:28 -0700 | [diff] [blame^] | 12 | On Linux (Debian): |
| 13 | |
| 14 | Note: you will need to add the Debian 'unstable' distribution to your source |
| 15 | file first. |
| 16 | |
| 17 | Add the following line to your `/etc/apt/sources.list` file: |
| 18 | |
| 19 | deb http://ftp.us.debian.org/debian unstable main contrib non-free |
| 20 | |
| 21 | Install the gRPC library |
| 22 | $ sudo apt-get install libgrpc-dev |
| 23 | |
| 24 | OR |
| 25 | |
Dan Ciruli | de3c654 | 2015-02-25 12:50:09 -0800 | [diff] [blame] | 26 | $ git clone https://github.com/grpc/grpc.git |
Dan Ciruli | 4175d84 | 2015-02-25 16:24:22 -0800 | [diff] [blame] | 27 | $ cd grpc |
Dan Ciruli | de3c654 | 2015-02-25 12:50:09 -0800 | [diff] [blame] | 28 | $ git submodule update --init |
Dan Ciruli | 4175d84 | 2015-02-25 16:24:22 -0800 | [diff] [blame] | 29 | $ make |
| 30 | $ sudo make install |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 31 | |
Nicolas Noble | c70752a | 2015-02-12 17:01:52 -0800 | [diff] [blame] | 32 | You don't need anything else than GNU Make, gcc and autotools. Under a Debian |
| 33 | or Ubuntu system, this should boil down to the following packages: |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 34 | |
Stanley Cheung | dbeb1cd | 2015-08-19 08:20:06 -0700 | [diff] [blame] | 35 | $ apt-get install build-essential autoconf libtool |
Nicolas Noble | c70752a | 2015-02-12 17:01:52 -0800 | [diff] [blame] | 36 | |
| 37 | Building the python wrapper requires the following: |
| 38 | |
Stanley Cheung | dbeb1cd | 2015-08-19 08:20:06 -0700 | [diff] [blame] | 39 | $ apt-get install python-all-dev python-virtualenv |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 40 | |
Nicolas "Pixel" Noble | 522d712 | 2015-02-19 01:28:02 +0100 | [diff] [blame] | 41 | If you want to install in a different directory than the default /usr/lib, you can |
| 42 | override it on the command line: |
| 43 | |
Stanley Cheung | dbeb1cd | 2015-08-19 08:20:06 -0700 | [diff] [blame] | 44 | $ make install prefix=/opt |
Nicolas "Pixel" Noble | 522d712 | 2015-02-19 01:28:02 +0100 | [diff] [blame] | 45 | |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 46 | |
| 47 | ******************************* |
| 48 | * More detailled instructions * |
| 49 | ******************************* |
| 50 | |
| 51 | Setting up dependencies |
| 52 | ======================= |
| 53 | |
| 54 | Dependencies to compile the libraries |
| 55 | ------------------------------------- |
| 56 | |
| 57 | grpc libraries have few external dependencies. If you need to compile and |
| 58 | install them, they are present in the third_party directory if you have |
| 59 | cloned the github repository recursively. If you didn't clone recursively, |
| 60 | you can still get them later by running the following command: |
| 61 | |
| 62 | $ git submodule update --init |
nnoble | 0005b77 | 2014-12-10 16:25:34 -0800 | [diff] [blame] | 63 | |
nnoble | 69ac39f | 2014-12-12 15:43:38 -0800 | [diff] [blame] | 64 | Note that the Makefile makes it much easier for you to compile from sources |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 65 | if you were to clone recursively our git repository: it will automatically |
| 66 | compile zlib and OpenSSL, which are core requirements for grpc. Note this |
| 67 | creates grpc libraries that will have zlib and OpenSSL built-in inside of them, |
| 68 | which significantly increases the libraries' size. |
| 69 | |
| 70 | In order to decrease that size, you can manually install zlib and OpenSSL on |
| 71 | your system, so that the Makefile can use them instead. |
| 72 | |
| 73 | Under a Debian or Ubuntu system, one can acquire the development package |
| 74 | for zlib this way: |
| 75 | |
| 76 | # apt-get install zlib1g-dev |
| 77 | |
| 78 | To the best of our knowledge, no distribution has an OpenSSL package that |
| 79 | supports ALPN yet, so you would still have to depend on installing from source |
| 80 | for that particular dependency if you want to reduce the libraries' size. |
| 81 | |
| 82 | The recommended version of OpenSSL that provides ALPN support is available |
| 83 | at this URL: |
| 84 | |
Nicolas "Pixel" Noble | d566021 | 2015-01-23 20:35:49 +0100 | [diff] [blame] | 85 | https://www.openssl.org/source/openssl-1.0.2.tar.gz |
nnoble | 69ac39f | 2014-12-12 15:43:38 -0800 | [diff] [blame] | 86 | |
nnoble | 0005b77 | 2014-12-10 16:25:34 -0800 | [diff] [blame] | 87 | |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 88 | Dependencies to compile and run the tests |
| 89 | ----------------------------------------- |
nnoble | 0005b77 | 2014-12-10 16:25:34 -0800 | [diff] [blame] | 90 | |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 91 | Compiling and running grpc plain-C tests dont't require any more dependency. |
nnoble | 0005b77 | 2014-12-10 16:25:34 -0800 | [diff] [blame] | 92 | |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 93 | |
| 94 | Compiling and running grpc C++ tests depend on protobuf 3.0.0, gtest and |
Nicolas Noble | c70752a | 2015-02-12 17:01:52 -0800 | [diff] [blame] | 95 | gflags. Although gflags is provided in third_party, you will need to manually |
| 96 | install that dependency on your system to run these tests. |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 97 | |
| 98 | Under a Debian or Ubuntu system, you can install the gtests and gflags packages |
| 99 | using apt-get: |
| 100 | |
| 101 | # apt-get install libgflags-dev libgtest-dev |
| 102 | |
Nicolas Noble | c70752a | 2015-02-12 17:01:52 -0800 | [diff] [blame] | 103 | However, protobuf 3.0.0 isn't in a debian package yet, but the Makefile will |
| 104 | automatically try and compile the one present in third_party if you cloned the |
| 105 | repository recursively, and that it detects your system is lacking it. |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 106 | |
| 107 | Compiling and installing protobuf 3.0.0 requires a few more dependencies in |
Nicolas Noble | c70752a | 2015-02-12 17:01:52 -0800 | [diff] [blame] | 108 | itself, notably the autoconf suite. If you have apt-get, you can install |
| 109 | these dependencies this way: |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 110 | |
Nicolas Noble | c70752a | 2015-02-12 17:01:52 -0800 | [diff] [blame] | 111 | # apt-get install autoconf libtool |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 112 | |
Nicolas "Pixel" Noble | d66cba2 | 2015-02-14 02:59:12 +0100 | [diff] [blame] | 113 | If you want to run the tests using one of the sanitized configurations, you |
| 114 | will need clang and its instrumented libc++: |
| 115 | |
| 116 | # apt-get install clang libc++-dev |
| 117 | |
vjpai | 7cc2c30 | 2015-02-18 12:33:37 -0800 | [diff] [blame] | 118 | Mac-specific notes: |
| 119 | ------------------- |
| 120 | |
| 121 | For a Mac system, git is not available by default. You will first need to |
| 122 | install Xcode from the Mac AppStore and then run the following command from a |
| 123 | terminal: |
| 124 | |
| 125 | $ sudo xcode-select --install |
| 126 | |
| 127 | You should also install "port" following the instructions at |
| 128 | https://www.macports.org . This will reside in /opt/local/bin/port for |
| 129 | most Mac installations. Do the "git submodule" command listed above. |
| 130 | |
| 131 | Then execute the following for all the needed build dependencies |
| 132 | |
| 133 | $ sudo /opt/local/bin/port install autoconf automake libtool gflags cmake |
Jorge Canizales | 123e5d8 | 2015-07-22 21:11:41 -0700 | [diff] [blame] | 134 | $ mkdir ~/gtest-svn |
vjpai | 7cc2c30 | 2015-02-18 12:33:37 -0800 | [diff] [blame] | 135 | $ svn checkout http://googletest.googlecode.com/svn/trunk/ gtest-svn |
| 136 | $ mkdir mybuild |
| 137 | $ cd mybuild |
| 138 | $ cmake ../gtest-svn |
| 139 | $ make |
| 140 | $ make gtest.a gtest_main.a |
| 141 | $ sudo cp libgtest.a libgtest_main.a /opt/local/lib |
| 142 | $ sudo mkdir /opt/local/include/gtest |
| 143 | $ sudo cp -pr ../gtest-svn/include/gtest /opt/local/include/gtest |
| 144 | |
| 145 | We will also need to make openssl and install it appropriately |
| 146 | |
| 147 | $ cd <git directory> |
| 148 | $ cd third_party/openssl |
vjpai | 37b9ec1 | 2015-08-10 10:02:09 -0700 | [diff] [blame] | 149 | $ ./config |
vjpai | 7cc2c30 | 2015-02-18 12:33:37 -0800 | [diff] [blame] | 150 | $ sudo make install |
| 151 | $ cd ../../ |
| 152 | |
| 153 | If you are going to make changes and need to regenerate the projects file, |
| 154 | you will need to install certain modules for python. |
| 155 | |
| 156 | $ sudo easy_install simplejson mako |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 157 | |
Nicolas "Pixel" Noble | 5fc1adf | 2015-05-10 22:20:31 +0200 | [diff] [blame] | 158 | Mingw-specific notes: |
| 159 | --------------------- |
| 160 | |
| 161 | While gRPC compiles properly under mingw, some more preparation work is needed. |
| 162 | The recommendation is to use msys2. The installation instructions are available |
| 163 | at that address: http://msys2.github.io/ |
| 164 | |
| 165 | Once this is installed, make sure you are using the following: MinGW-w64 Win64. |
| 166 | You'll be required to install a few more packages: |
| 167 | |
| 168 | $ pacman -S make mingw-w64-x86_64-gcc mingw-w64-x86_64-zlib autoconf automake libtool |
| 169 | |
| 170 | Please also install OpenSSL from that website: |
| 171 | |
| 172 | http://slproweb.com/products/Win32OpenSSL.html |
| 173 | |
| 174 | The package Win64 OpenSSL v1.0.2a should do. At that point you should be able |
| 175 | to compile gRPC with the following: |
| 176 | |
| 177 | $ export LDFLAGS="-L/mingw64/lib -L/c/OpenSSL-Win64" |
| 178 | $ export CPPFLAGS="-I/mingw64/include -I/c/OpenSSL-Win64/include" |
| 179 | $ make |
| 180 | |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 181 | A word on OpenSSL |
| 182 | ----------------- |
nnoble | 0005b77 | 2014-12-10 16:25:34 -0800 | [diff] [blame] | 183 | |
Abhishek Kumar | 3dd9df9 | 2015-02-10 10:16:41 -0800 | [diff] [blame] | 184 | Secure HTTP2 requires the TLS extension ALPN (see rfc 7301 and |
nnoble | 0005b77 | 2014-12-10 16:25:34 -0800 | [diff] [blame] | 185 | http://http2.github.io/http2-spec/ section 3.3). Our HTTP2 implementation |
Nicolas "Pixel" Noble | d566021 | 2015-01-23 20:35:49 +0100 | [diff] [blame] | 186 | relies on OpenSSL's implementation. OpenSSL 1.0.2 is the first released version |
nnoble | 0005b77 | 2014-12-10 16:25:34 -0800 | [diff] [blame] | 187 | of OpenSSL that has ALPN support, and this explains our dependency on it. |
| 188 | |
nnoble | 69ac39f | 2014-12-12 15:43:38 -0800 | [diff] [blame] | 189 | Note that the Makefile supports compiling only the unsecure elements of grpc, |
| 190 | and if you do not have OpenSSL and do not want it, you can still proceed |
Abhishek Kumar | 6749e73 | 2015-02-10 10:59:52 -0800 | [diff] [blame] | 191 | with installing only the elements you require. However, we strongly recommend |
Abhishek Kumar | 3dd9df9 | 2015-02-10 10:16:41 -0800 | [diff] [blame] | 192 | the use of encryption for all network traffic, and discourage the use of grpc |
| 193 | without TLS. |
nnoble | 69ac39f | 2014-12-12 15:43:38 -0800 | [diff] [blame] | 194 | |
nnoble | 0005b77 | 2014-12-10 16:25:34 -0800 | [diff] [blame] | 195 | |
| 196 | Compiling |
| 197 | ========= |
| 198 | |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 199 | If you have all the dependencies mentioned above, you should simply be able |
| 200 | to go ahead and run "make" to compile grpc's C and C++ libraries: |
nnoble | 0005b77 | 2014-12-10 16:25:34 -0800 | [diff] [blame] | 201 | |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 202 | $ make |
nnoble | 0005b77 | 2014-12-10 16:25:34 -0800 | [diff] [blame] | 203 | |
| 204 | |
| 205 | Testing |
| 206 | ======= |
| 207 | |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 208 | To build and run the tests, you can run the command: |
nnoble | 0005b77 | 2014-12-10 16:25:34 -0800 | [diff] [blame] | 209 | |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 210 | $ make test |
| 211 | |
| 212 | If you want to be able to run them in parallel, and get better output, you can |
| 213 | also use the python tool we have written: |
| 214 | |
| 215 | $ ./tools/run_tests/run_tests.py |
nnoble | 0005b77 | 2014-12-10 16:25:34 -0800 | [diff] [blame] | 216 | |
| 217 | |
| 218 | Installing |
| 219 | ========== |
| 220 | |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 221 | Once everything is compiled, you should be able to install grpc C and C++ |
nnoble | 0005b77 | 2014-12-10 16:25:34 -0800 | [diff] [blame] | 222 | libraries and headers: |
| 223 | |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 224 | # make install |