1Building gRPC-Java 2================== 3 4Building is only necessary if you are making changes to gRPC-Java. 5 6Building requires JDK 8, as our tests use TLS. 7 8grpc-java has a C++ code generation plugin for protoc. Since many Java 9developers don't have C compilers installed and don't need to modify the 10codegen, the build can skip it. To skip, create the file 11`<project-root>/gradle.properties` and add `skipCodegen=true`. 12 13Then, to build, run: 14``` 15$ ./gradlew build 16``` 17 18To install the artifacts to your Maven local repository for use in your own 19project, run: 20``` 21$ ./gradlew install 22``` 23 24### Notes for IntelliJ 25Building in IntelliJ works best when you import the project as a Gradle project and delegate IDE 26build/run actions to Gradle. 27 28You can find this setting at: 29```Settings -> Build, Execution, Deployment 30 -> Build Tools -> Gradle -> Runner 31 -> Delegate IDE build/run actions to gradle. 32``` 33 34How to Build Code Generation Plugin 35----------------------------------- 36This section is only necessary if you are making changes to the code 37generation. Most users only need to use `skipCodegen=true` as discussed above. 38 39### Build Protobuf 40The codegen plugin is C++ code and requires protobuf 3.0.0 or later. 41 42For Linux, Mac and MinGW: 43``` 44$ git clone https://github.com/google/protobuf.git 45$ cd protobuf 46$ git checkout v3.5.1 47$ ./autogen.sh 48$ ./configure 49$ make 50$ make check 51$ sudo make install 52``` 53 54If you are comfortable with C++ compilation and autotools, you can specify a 55``--prefix`` for Protobuf and use ``-I`` in ``CXXFLAGS``, ``-L`` in 56``LDFLAGS``, ``LD_LIBRARY_PATH``, and ``PATH`` to reference it. The 57environment variables will be used when building grpc-java. 58 59Protobuf installs to ``/usr/local`` by default. 60 61For Visual C++, please refer to the [Protobuf README](https://github.com/google/protobuf/blob/master/cmake/README.md) 62for how to compile Protobuf. gRPC-java assumes a Release build. 63 64#### Linux and MinGW 65If ``/usr/local/lib`` is not in your library search path, you can add it by running: 66``` 67$ sudo sh -c 'echo /usr/local/lib >> /etc/ld.so.conf' 68$ sudo ldconfig 69``` 70 71#### Mac 72Some versions of Mac OS X (e.g., 10.10) doesn't have ``/usr/local`` in the 73default search paths for header files and libraries. It will fail the build of 74the codegen. To work around this, you will need to set environment variables: 75``` 76$ export CXXFLAGS="-I/usr/local/include" LDFLAGS="-L/usr/local/lib" 77``` 78 79### Notes for Visual C++ 80 81When building on Windows and VC++, you need to specify project properties for 82Gradle to find protobuf: 83``` 84.\gradlew install ^ 85 -PvcProtobufInclude=C:\path\to\protobuf-3.5.1\src ^ 86 -PvcProtobufLibs=C:\path\to\protobuf-3.5.1\vsprojects\Release ^ 87 -PtargetArch=x86_32 88``` 89 90Since specifying those properties every build is bothersome, you can instead 91create ``<project-root>\gradle.properties`` with contents like: 92``` 93vcProtobufInclude=C:\\path\\to\\protobuf-3.5.1\\src 94vcProtobufLibs=C:\\path\\to\\protobuf-3.5.1\\vsprojects\\Release 95targetArch=x86_32 96``` 97 98By default, the build script will build the codegen for the same architecture as 99the Java runtime installed on your system. If you are using 64-bit JVM, the 100codegen will be compiled for 64-bit. Since Protobuf is only built for 32-bit by 101default, the `targetArch=x86_32` is necessary. 102 103### Notes for MinGW on Windows 104If you have both MinGW and VC++ installed on Windows, VC++ will be used by 105default. To override this default and use MinGW, add ``-PvcDisable=true`` 106to your Gradle command line or add ``vcDisable=true`` to your 107``<project-root>\gradle.properties``. 108 109### Notes for Unsupported Operating Systems 110The build script pulls pre-compiled ``protoc`` from Maven Central by default. 111We have built ``protoc`` binaries for popular systems, but they may not work 112for your system. If ``protoc`` cannot be downloaded or would not run, you can 113use the one that has been built by your own, by adding this property to 114``<project-root>/gradle.properties``: 115``` 116protoc=/path/to/protoc 117``` 118