diff --git a/DEPLOYING.md b/DEPLOYING.md new file mode 100644 index 0000000000..f8bc243804 --- /dev/null +++ b/DEPLOYING.md @@ -0,0 +1,195 @@ +How to Deploy GRPC Java to Maven Central (for Maintainers Only) +=============================================================== + +Build Environments +------------------ +We have succesfully deployed GRPC to Maven Central under the following systems: +- Ubuntu 14.04 64-bit +- Windows 7 64-bit with MSYS2 with mingw32 and mingw64 +- Mac OS X 10.9.5 + +Other systems may also work, but we haven't verified them. + +Prerequisites +------------- + +### Setup OSSRH and Signing + +If you haven't deployed artifacts to Maven Central before, you need to setup +your OSSRH account and signing keys. +- Follow the instructions on [this + page](http://central.sonatype.org/pages/ossrh-guide.html) to set up an + account with OSSRH. +- (For release deployment only) Install GnuPG and [generate your key + pair](https://www.gnupg.org/documentation/howtos.html) +- Put your GnuPG key password and OSSRH account information in + ``/.gradle/gradle.properties``. + +``` +# You need the signing properties only if you are making release deployment +signing.keyId=<8-character-public-key-id> +signing.password= +signing.secretKeyRingFile=/.gnupg/secring.gpg + +ossrhUsername= +ossrhPassword= +checkstyle.ignoreFailures=false +``` + +### Build Protobuf +Protobuf libraries are needed for compiling the GRPC codegen. Despite that you +may have installed Protobuf on your system, you may want to build Protobuf +separately and install it under your personal directory, because + +1. The Protobuf version installed on your system may be different from what + GRPC requires. You may not want to pollute your system installation. +2. We will deploy both 32-bit and 64-bit versions of the codegen, thus require + both variants of Protobuf libraries. You don't want to mix them in your + system paths. + + +#### Linux +You must have multilib GCC installed on your system. + +Compile and install 32-bit protobuf: +``` +protobuf$ CXXFLAGS="-m32" ./configure --disable-shared --prefix=$HOME/protobuf-32 +protobuf$ make clean && make && make install +``` + +Compile and install 64-bit protobuf: +``` +protobuf$ CXXFLAGS="-m64" ./configure --disable-shared --prefix=$HOME/protobuf-64 +protobuf$ make clean && make && make install +``` + + +#### Windows 64-bit with MSYS2 (Recommended for Windows) +Because the gcc shipped with MSYS2 doesn't support multilib, you have to +compile and deploy 32-bit and 64-bit binaries in separate steps. + +##### Under MinGW-w64 Win32 Shell +Compile and install 32-bit protobuf: +``` +protobuf$ ./configure --disable-shared --prefix=$HOME/protobuf-32 +protobuf$ make clean && make && make install +``` + +##### Under MinGW-w64 Win64 Shell +Compile and install 64-bit protobuf: +``` +protobuf$ ./configure --disable-shared --prefix=$HOME/protobuf-64 +protobuf$ make clean && make && make install +``` + + +#### Windows 64-bit with Cygwin64 (TODO: incomplete) +Because the MinGW gcc shipped with Cygwin64 doesn't support multilib, you have +to compile and deploy 32-bit and 64-bit binaries in separate steps. + +Compile and install 32-bit protobuf. ``-static-libgcc -static-libstdc++`` are +needed for ``protoc`` to be successfully run in the unit test. +``` +protobuf$ LDFLAGS="-static-libgcc -static-libstdc++" ./configure --host=i686-w64-mingw32 --disable-shared --prefix=$HOME/protobuf-32 +protobuf$ make clean && make && make install +``` + +Compile and install 64-bit protobuf: +``` +protobuf$ ./configure --host=x86_64-w64-mingw32 --disable-shared --prefix=$HOME/protobuf-64 +protobuf$ make clean && make && make install +``` + + +#### Mac +Please refer to [Protobuf +README](https://github.com/google/protobuf/blob/master/README.md) for how to +set up GCC and Unix tools on Mac. + +Mac OS X has been 64-bit-only since 10.7 and we are compiling for 10.7 and up. +We only build 64-bit artifact for Mac. + +Compile and install protobuf: +``` +protobuf$ CXXFLAGS="-m64" ./configure --disable-shared --prefix=$HOME/protobuf +protobuf$ make clean && make && make install +``` + +Build and Deploy +---------------- +You may want to open a shell dedicated for the following tasks, because you +will set a few environment variables which is only used in deployment. + + +### Setup Environment Variables + +Compilation of the codegen requires additional environment variables to locate +the header files and libraries of Protobuf. + +#### Linux +``` +$ export CXXFLAGS="-I$HOME/protobuf-32/include" \ + LDFLAGS="-L$HOME/protobuf-32/lib -L$HOME/protobuf-64/lib" \ + TARGET_ARCHS="x86_32 x86_64" +``` + +#### Windows 64-bit with MSYS2 + +##### Under MinGW-w64 Win32 Shell + +``` +$ export CXXFLAGS="-I$HOME/protobuf-32/include" \ + LDFLAGS="-L$HOME/protobuf-32/lib" \ + TARGET_ARCHS="x86_32" +``` + +##### Under MinGW-w64 Win64 Shell +``` +$ export CXXFLAGS="-I$HOME/protobuf-64/include" \ + LDFLAGS="-L$HOME/protobuf-64/lib" \ + TARGET_ARCHS="x86_64" +``` + + +#### Mac +``` +$ export CXXFLAGS="-I$HOME/protobuf/include" \ + LDFLAGS="$HOME/protobuf/lib/libprotobuf.a $HOME/protobuf/lib/libprotoc.a" \ + TARGET_ARCHS="x86_64" +``` + + + +### Deploy the Entire Project + +The following command will build the whole project and upload it to Maven +Central. +``` +grpc-java$ ./gradlew clean uploadArchives +``` + +If the version has the ``SNAPSHOT`` suffix, the artifacts will automatically +go to the snapshot repository. Otherwise it's a release deployment and the +artifacts will go to a freshly created staging repository. + + +### Deploy GRPC Codegen for Additional Platforms +The previous step will only deploy the codegen artifacts for the platform you +run on it. For a fully fledged deployment, you will need to deploy the codegen +for all other supported platforms. To do so, move on the next platform, set up +the prerequisites and environment variables, then + +If you are doing a snapshot deployment: +``` +grpc-java$ ./gradlew clean grpc-compiler:uploadArchives +``` + +If you are doing a release deployment: +``` +grpc-java$ ./gradlew clean grpc-compiler:uploadArchives -DrepositoryId= +``` +where ```` is the ID of the staging repository that you have +found from the OSSRH UI after the first deployment, usually in the form of +``iogrpc-*``. This makes sure the additional codegen artifacts go to the same +repository as the main project is in. + diff --git a/README.md b/README.md index 8d935fa642..66dc8c3739 100644 --- a/README.md +++ b/README.md @@ -59,7 +59,7 @@ Navigating Around the Source ---------------------------- Heres a quick readers guide to the code to help folks get started. At a high level there are three distinct layers -to the library: stub, channel & transport. +to the library: stub, channel & transport. ### Stub diff --git a/compiler/README.md b/compiler/README.md index 26ed67cd17..cb442ee1fe 100644 --- a/compiler/README.md +++ b/compiler/README.md @@ -52,131 +52,5 @@ $ ../gradlew install ``` ## Pushing the codegen to Maven Central -This will compile both the 32-bit and 64-bit versions of the codegen and upload -them to Maven Central. - -You need to have both the 32-bit and 64-bit versions of Protobuf installed. -It's recommended that you install Protobuf to custom locations (e.g., -``~/protobuf-3.0.0-32`` and ``~/protobuf-3.0.0-64``) rather than the system -default location, so that different version of Protobuf won't mess up. It -should also be compiled statically linked. - -Generally speaking, to compile and install both 32-bit and 64-bit artifacts -locally. You may want to use ``--info`` so that you know what executables are -produced. -``` -$ TARGET_ARCHS="" ../gradlew install --info -``` - -To compile and upload the artifacts to Maven Central: -``` -$ TARGET_ARCHS="" ../gradlew uploadArchives -``` - -It's recommended that you run ``install --info`` prior to ``uploadArchives`` -and examine the produced artifacts before running ``uploadArchives``. - -Additional environments need to be set so that the compiler and linker can find -the protobuf headers and libraries. Follow the platform-specific instructions -below. - -### Note for using Sonatype OSSRH services - -A full fledged release is done by running ``uploadArchives`` on multiple -platforms. After you have successfully run ``uploadArchives`` on the first -platfrom, you should go to OSSRH UI and find the staging repository that has -been automatically created. At the subsequent runs of ``uploadArchives``, you -need to append ``-DrepositoryId=`` to your -command line, so that the artifacts can be merged in a single release. - -### Linux -You must have multilib GCC installed on your system. - -Compile and install 32-bit protobuf: -``` -protobuf$ CXXFLAGS="-m32" ./configure --disable-shared --prefix=$HOME/protobuf-32 -protobuf$ make clean && make && make install -``` - -Compile and install 64-bit protobuf: -``` -protobuf$ CXXFLAGS="-m64" ./configure --disable-shared --prefix=$HOME/protobuf-64 -protobuf$ make clean && make && make install -``` - -Compile and deploy GRPC codegen: -``` -$ CXXFLAGS="-I$HOME/protobuf-32/include" \ - LDFLAGS="-L$HOME/protobuf-32/lib -L$HOME/protobuf-64/lib" \ - TARGET_ARCHS="x86_32 x86_64" ../gradlew uploadArchives -``` - -### Windows 64-bit with MSYS2 (Recommended for Windows) -Because the gcc shipped with MSYS2 doesn't support multilib, you have to -compile and deploy 32-bit and 64-bit binaries in separate steps. - -#### Under MinGW-w64 Win32 Shell -Compile and install 32-bit protobuf: -``` -protobuf$ ./configure --disable-shared --prefix=$HOME/protobuf-32 -protobuf$ make clean && make && make install -``` - -Compile and deploy GRPC 32-bit codegen -``` -$ CXXFLAGS="-I$HOME/protobuf-32/include" \ - LDFLAGS="-L$HOME/protobuf-32/lib" \ - TARGET_ARCHS="x86_32" ../gradlew uploadArchives -``` - -#### Under MinGW-w64 Win64 Shell -Compile and install 64-bit protobuf: -``` -protobuf$ ./configure --disable-shared --prefix=$HOME/protobuf-64 -protobuf$ make clean && make && make install -``` - -Compile and deploy GRPC 64-bit codegen: -``` -$ CXXFLAGS="-I$HOME/protobuf-64/include" \ - LDFLAGS="-L$HOME/protobuf-64/lib" \ - TARGET_ARCHS="x86_64" ../gradlew uploadArchives -``` - -### Windows 64-bit with Cygwin64 (TODO: incomplete) -Because the MinGW gcc shipped with Cygwin64 doesn't support multilib, you have -to compile and deploy 32-bit and 64-bit binaries in separate steps. - -Compile and install 32-bit protobuf. ``-static-libgcc -static-libstdc++`` are -needed for ``protoc`` to be successfully run in the unit test. -``` -protobuf$ LDFLAGS="-static-libgcc -static-libstdc++" ./configure --host=i686-w64-mingw32 --disable-shared --prefix=$HOME/protobuf-32 -protobuf$ make clean && make && make install -``` - -Compile and install 64-bit protobuf: -``` -protobuf$ ./configure --host=x86_64-w64-mingw32 --disable-shared --prefix=$HOME/protobuf-64 -protobuf$ make clean && make && make install -``` - -### Mac -Please refer to [Protobuf -README](https://github.com/google/protobuf/blob/master/README.md) for how to -set up GCC and Unix tools on Mac. - -Mac OS X has been 64-bit-only since 10.7 and we are compiling for 10.7 and up. -We only build 64-bit artifact for Mac. - -Compile and install protobuf: -``` -protobuf$ CXXFLAGS="-m64" ./configure --disable-shared --prefix=$HOME/protobuf -protobuf$ make clean && make && make install -``` - -Compile and deploy GRPC codegen: -``` -$ CXXFLAGS="-I$HOME/protobuf/include" \ - LDFLAGS="$HOME/protobuf/lib/libprotobuf.a $HOME/protobuf/lib/libprotoc.a" \ - TARGET_ARCHS="x86_64" ../gradlew uploadArchives -``` +Please follow the instructions in ``DEPLOYING.md`` under the root directory for +deploying the codegen to Maven Central.