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 | |
Dan Ciruli | de3c654 | 2015-02-25 12:50:09 -0800 | [diff] [blame] | 12 | $ git clone https://github.com/grpc/grpc.git |
| 13 | $ git submodule update --init |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 14 | |
Dan Ciruli | de3c654 | 2015-02-25 12:50:09 -0800 | [diff] [blame] | 15 | $ make |
| 16 | $ sudo make install |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 17 | |
Nicolas Noble | c70752a | 2015-02-12 17:01:52 -0800 | [diff] [blame] | 18 | You don't need anything else than GNU Make, gcc and autotools. Under a Debian |
| 19 | or Ubuntu system, this should boil down to the following packages: |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 20 | |
Dan Ciruli | de3c654 | 2015-02-25 12:50:09 -0800 | [diff] [blame] | 21 | $ apt-get install build-essential autoconf libtool |
Nicolas Noble | c70752a | 2015-02-12 17:01:52 -0800 | [diff] [blame] | 22 | |
| 23 | Building the python wrapper requires the following: |
| 24 | |
| 25 | # apt-get install python-all-dev python-virtualenv |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 26 | |
Nicolas "Pixel" Noble | 522d712 | 2015-02-19 01:28:02 +0100 | [diff] [blame] | 27 | If you want to install in a different directory than the default /usr/lib, you can |
| 28 | override it on the command line: |
| 29 | |
| 30 | # make install prefix=/opt |
| 31 | |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 32 | |
| 33 | ******************************* |
| 34 | * More detailled instructions * |
| 35 | ******************************* |
| 36 | |
| 37 | Setting up dependencies |
| 38 | ======================= |
| 39 | |
| 40 | Dependencies to compile the libraries |
| 41 | ------------------------------------- |
| 42 | |
| 43 | grpc libraries have few external dependencies. If you need to compile and |
| 44 | install them, they are present in the third_party directory if you have |
| 45 | cloned the github repository recursively. If you didn't clone recursively, |
| 46 | you can still get them later by running the following command: |
| 47 | |
| 48 | $ git submodule update --init |
nnoble | 0005b77 | 2014-12-10 16:25:34 -0800 | [diff] [blame] | 49 | |
nnoble | 69ac39f | 2014-12-12 15:43:38 -0800 | [diff] [blame] | 50 | 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] | 51 | if you were to clone recursively our git repository: it will automatically |
| 52 | compile zlib and OpenSSL, which are core requirements for grpc. Note this |
| 53 | creates grpc libraries that will have zlib and OpenSSL built-in inside of them, |
| 54 | which significantly increases the libraries' size. |
| 55 | |
| 56 | In order to decrease that size, you can manually install zlib and OpenSSL on |
| 57 | your system, so that the Makefile can use them instead. |
| 58 | |
| 59 | Under a Debian or Ubuntu system, one can acquire the development package |
| 60 | for zlib this way: |
| 61 | |
| 62 | # apt-get install zlib1g-dev |
| 63 | |
| 64 | To the best of our knowledge, no distribution has an OpenSSL package that |
| 65 | supports ALPN yet, so you would still have to depend on installing from source |
| 66 | for that particular dependency if you want to reduce the libraries' size. |
| 67 | |
| 68 | The recommended version of OpenSSL that provides ALPN support is available |
| 69 | at this URL: |
| 70 | |
Nicolas "Pixel" Noble | d566021 | 2015-01-23 20:35:49 +0100 | [diff] [blame] | 71 | https://www.openssl.org/source/openssl-1.0.2.tar.gz |
nnoble | 69ac39f | 2014-12-12 15:43:38 -0800 | [diff] [blame] | 72 | |
nnoble | 0005b77 | 2014-12-10 16:25:34 -0800 | [diff] [blame] | 73 | |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 74 | Dependencies to compile and run the tests |
| 75 | ----------------------------------------- |
nnoble | 0005b77 | 2014-12-10 16:25:34 -0800 | [diff] [blame] | 76 | |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 77 | Compiling and running grpc plain-C tests dont't require any more dependency. |
nnoble | 0005b77 | 2014-12-10 16:25:34 -0800 | [diff] [blame] | 78 | |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 79 | |
| 80 | 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] | 81 | gflags. Although gflags is provided in third_party, you will need to manually |
| 82 | install that dependency on your system to run these tests. |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 83 | |
| 84 | Under a Debian or Ubuntu system, you can install the gtests and gflags packages |
| 85 | using apt-get: |
| 86 | |
| 87 | # apt-get install libgflags-dev libgtest-dev |
| 88 | |
Nicolas Noble | c70752a | 2015-02-12 17:01:52 -0800 | [diff] [blame] | 89 | However, protobuf 3.0.0 isn't in a debian package yet, but the Makefile will |
| 90 | automatically try and compile the one present in third_party if you cloned the |
| 91 | repository recursively, and that it detects your system is lacking it. |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 92 | |
| 93 | 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] | 94 | itself, notably the autoconf suite. If you have apt-get, you can install |
| 95 | these dependencies this way: |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 96 | |
Nicolas Noble | c70752a | 2015-02-12 17:01:52 -0800 | [diff] [blame] | 97 | # apt-get install autoconf libtool |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 98 | |
Nicolas "Pixel" Noble | d66cba2 | 2015-02-14 02:59:12 +0100 | [diff] [blame] | 99 | If you want to run the tests using one of the sanitized configurations, you |
| 100 | will need clang and its instrumented libc++: |
| 101 | |
| 102 | # apt-get install clang libc++-dev |
| 103 | |
vjpai | 7cc2c30 | 2015-02-18 12:33:37 -0800 | [diff] [blame] | 104 | Mac-specific notes: |
| 105 | ------------------- |
| 106 | |
| 107 | For a Mac system, git is not available by default. You will first need to |
| 108 | install Xcode from the Mac AppStore and then run the following command from a |
| 109 | terminal: |
| 110 | |
| 111 | $ sudo xcode-select --install |
| 112 | |
| 113 | You should also install "port" following the instructions at |
| 114 | https://www.macports.org . This will reside in /opt/local/bin/port for |
| 115 | most Mac installations. Do the "git submodule" command listed above. |
| 116 | |
| 117 | Then 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 | |
| 131 | We 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 | |
| 138 | If you are going to make changes and need to regenerate the projects file, |
| 139 | you will need to install certain modules for python. |
| 140 | |
| 141 | $ sudo easy_install simplejson mako |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 142 | |
| 143 | A word on OpenSSL |
| 144 | ----------------- |
nnoble | 0005b77 | 2014-12-10 16:25:34 -0800 | [diff] [blame] | 145 | |
Abhishek Kumar | 3dd9df9 | 2015-02-10 10:16:41 -0800 | [diff] [blame] | 146 | Secure HTTP2 requires the TLS extension ALPN (see rfc 7301 and |
nnoble | 0005b77 | 2014-12-10 16:25:34 -0800 | [diff] [blame] | 147 | 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] | 148 | 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] | 149 | of OpenSSL that has ALPN support, and this explains our dependency on it. |
| 150 | |
nnoble | 69ac39f | 2014-12-12 15:43:38 -0800 | [diff] [blame] | 151 | Note that the Makefile supports compiling only the unsecure elements of grpc, |
| 152 | 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] | 153 | with installing only the elements you require. However, we strongly recommend |
Abhishek Kumar | 3dd9df9 | 2015-02-10 10:16:41 -0800 | [diff] [blame] | 154 | the use of encryption for all network traffic, and discourage the use of grpc |
| 155 | without TLS. |
nnoble | 69ac39f | 2014-12-12 15:43:38 -0800 | [diff] [blame] | 156 | |
nnoble | 0005b77 | 2014-12-10 16:25:34 -0800 | [diff] [blame] | 157 | |
| 158 | Compiling |
| 159 | ========= |
| 160 | |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 161 | If you have all the dependencies mentioned above, you should simply be able |
| 162 | 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] | 163 | |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 164 | $ make |
nnoble | 0005b77 | 2014-12-10 16:25:34 -0800 | [diff] [blame] | 165 | |
| 166 | |
| 167 | Testing |
| 168 | ======= |
| 169 | |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 170 | To build and run the tests, you can run the command: |
nnoble | 0005b77 | 2014-12-10 16:25:34 -0800 | [diff] [blame] | 171 | |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 172 | $ make test |
| 173 | |
| 174 | If you want to be able to run them in parallel, and get better output, you can |
| 175 | also use the python tool we have written: |
| 176 | |
| 177 | $ ./tools/run_tests/run_tests.py |
nnoble | 0005b77 | 2014-12-10 16:25:34 -0800 | [diff] [blame] | 178 | |
| 179 | |
| 180 | Installing |
| 181 | ========== |
| 182 | |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 183 | 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] | 184 | libraries and headers: |
| 185 | |
Nicolas Noble | 6ae8ef1 | 2015-01-16 15:03:42 -0800 | [diff] [blame] | 186 | # make install |