BUILDING.md

   1 gRPC C++ - Building from source
   2 ===========================
   3
   4 # Pre-requisites
   5
   6 ## Linux
   7
   8 ```sh
   9  $ [sudo] apt-get install build-essential autoconf libtool pkg-config
  10 ```
  11
  12 If you plan to build from source and run tests, install the following as well:
  13 ```sh
  14  $ [sudo] apt-get install libgflags-dev libgtest-dev
  15  $ [sudo] apt-get install clang-5.0 libc++-dev
  16 ```
  17 Lastly, see the Protoc section below if you do not yet have the protoc compiler installed.
  18
  19 ## MacOS
  20
  21 On a Mac, you will first need to
  22 install Xcode or
  23 [Command Line Tools for Xcode](https://developer.apple.com/download/more/)
  24 and then run the following command from a terminal:
  25
  26 ```sh
  27  $ [sudo] xcode-select --install
  28 ```
  29
  30 To build gRPC from source, you may need to install the following
  31 packages from [Homebrew](https://brew.sh):
  32
  33 ```sh
  34  $ brew install autoconf automake libtool shtool
  35 ```
  36
  37 If you plan to build from source and run tests, install the following as well:
  38 ```sh
  39  $ brew install gflags
  40 ```
  41
  42 *Tip*: when building,
  43 you *may* want to explicitly set the `LIBTOOL` and `LIBTOOLIZE`
  44 environment variables when running `make` to ensure the version
  45 installed by `brew` is being used:
  46
  47 ```sh
  48  $ LIBTOOL=glibtool LIBTOOLIZE=glibtoolize make
  49 ```
  50 Lastly, see the Protoc section below if you do not yet have the protoc compiler.
  51
  52 ## Windows
  53
  54 To prepare for cmake + Microsoft Visual C++ compiler build
  55 - Install Visual Studio 2015 or 2017 (Visual C++ compiler will be used).
  56 - Install [Git](https://git-scm.com/).
  57 - Install [CMake](https://cmake.org/download/).
  58 - Install [Active State Perl](https://www.activestate.com/activeperl/) (`choco install activeperl`) - *required by boringssl*
  59 - Install [Go](https://golang.org/dl/) (`choco install golang`) - *required by boringssl*
  60 - Install [yasm](http://yasm.tortall.net/) and add it to `PATH` (`choco install yasm`) - *required by boringssl*
  61 - (Optional) Install [Ninja](https://ninja-build.org/) (`choco install ninja`)
  62
  63 ## Protoc
  64
  65 By default gRPC uses [protocol buffers](https://github.com/google/protobuf),
  66 you will need the `protoc` compiler to generate stub server and client code.
  67
  68 If you compile gRPC from source, as described below, the Makefile will
  69 automatically try compiling the `protoc` in third_party if you cloned the
  70 repository recursively and it detects that you do not already have 'protoc' compiler
  71 installed.
  72
  73 If 'protoc' compiler has not been installed, following commands can be used for installation.
  74
  75 ```sh
  76 $ cd grpc/third_party/protobuf
  77 $ sudo make install   # 'make' should have been run by core grpc
  78 ```
  79
  80 # Clone the repository (including submodules)
  81
  82 Before building, you need to clone the gRPC github repository and download submodules containing source code
  83 for gRPC's dependencies (that's done by the `submodule` command or `--recursive` flag). The following commands will clone the gRPC
  84 repository at the latest stable version.
  85
  86 ## Unix
  87
  88 ```sh
  89  $ git clone -b $(curl -L https://grpc.io/release) https://github.com/grpc/grpc
  90  $ cd grpc
  91  $ git submodule update --init
  92  ```
  93
  94 ## Windows
  95
  96 ```
  97 > @rem You can also do just "git clone --recursive -b THE_BRANCH_YOU_WANT https://github.com/grpc/grpc"
  98 > powershell git clone --recursive -b ((New-Object System.Net.WebClient).DownloadString(\"https://grpc.io/release\").Trim()) https://github.com/grpc/grpc
  99 > cd grpc
 100 > @rem To update submodules at later time, run "git submodule update --init"
 101 ```
 102
 103 # Build from source
 104
 105 In the C++ world, there's no "standard" build system that would work for in all supported use cases and on all supported platforms.
 106 Therefore, gRPC supports several major build systems, which should satisfy most users.
 107
 108 Note that this section only covers the build of gRPC itself, not the installation. See the [How to use](https://github.com/grpc/grpc/tree/master/src/cpp#to-start-using-grpc-c) instructions
 109 for guidance on how to add gRPC as a dependency to a C++ application (there are several ways and system wide installation is often not the best choice).
 110
 111 ## make (on UNIX systems)
 112
 113 From the grpc repository root
 114 ```sh
 115  $ make
 116 ```
 117 NOTE: if you get an error on linux such as 'aclocal-1.15: command not found', which can happen if you ran 'make' before installing the pre-reqs, try the following:
 118 ```sh
 119 $ git clean -f -d -x && git submodule foreach --recursive git clean -f -d -x
 120 $ [sudo] apt-get install build-essential autoconf libtool pkg-config
 121 $ make
 122 ```
 123
 124 ## bazel
 125
 126 See [Installing Bazel](https://docs.bazel.build/versions/master/install.html) for instructions how to install bazel on your system.
 127
 128 From the grpc repository root
 129 ```
 130 $ bazel build :all
 131 ```
 132
 133 ## cmake: Windows, Using Visual Studio 2015 or 2017 (can only build with OPENSSL_NO_ASM).
 134 When using the "Visual Studio" generator,
 135 cmake will generate a solution (`grpc.sln`) that contains a VS project for
 136 every target defined in `CMakeLists.txt` (+ few extra convenience projects
 137 added automatically by cmake). After opening the solution with Visual Studio
 138 you will be able to browse and build the code.
 139 ```
 140 > @rem Run from grpc directory after cloning the repo with --recursive or updating submodules.
 141 > md .build
 142 > cd .build
 143 > cmake .. -G "Visual Studio 14 2015"
 144 > cmake --build . --config Release
 145 ```
 146
 147 ## cmake: Windows, Using Ninja (faster build, supports boringssl's assembly optimizations).
 148 Please note that when using Ninja, you will still need Visual C++ (part of Visual Studio)
 149 installed to be able to compile the C/C++ sources.
 150 ```
 151 > @rem Run from grpc directory after cloning the repo with --recursive or updating submodules.
 152 > md .build
 153 > cd .build
 154 > call "%VS140COMNTOOLS%..\..\VC\vcvarsall.bat" x64
 155 > cmake .. -GNinja -DCMAKE_BUILD_TYPE=Release
 156 > cmake --build .
 157 ```