grpc
/
grpc-java
mirror of https://github.com/grpc/grpc-java.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Reorganizing the deployment docs.

This commit is contained in:
nmittler 2015-06-08 14:32:37 -07:00
parent 0d03f89467
commit 483738e8bc
3 changed files with 293 additions and 214 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

211
DEPLOYING.md
View File

@ -1,211 +0,0 @@
How to Deploy GRPC Java to Maven Central (for Maintainers Only)
===============================================================
Build Environments
------------------
We deploy GRPC to Maven Central under the following systems:
- Ubuntu 14.04 with Docker 1.6.1 that runs CentOS 6.6
- 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
``<your-home-directory>/.gradle/gradle.properties``.
```
# You need the signing properties only if you are making release deployment
signing.keyId=<8-character-public-key-id>
signing.password=<key-password>
signing.secretKeyRingFile=<your-home-directory>/.gnupg/secring.gpg
ossrhUsername=<ossrh-username>
ossrhPassword=<ossrh-password>
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 with Docker
Build the ``protoc-artifacts`` image under the Protobuf source directory:
```
protobuf$ docker build -t protoc-artifacts protoc-artifacts
```
#### 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
Build the ``grpc-java-deploy`` image:
```
grpc-java$ docker build -t grpc-java-deploy compiler
```
Start a Docker container that has the deploy environment set up for you. The
gRPC source is cloned into ``/grpc-java``.
```
$ docker run -it --rm=true grpc-java-deploy
```
Note that the container will be deleted after you exit. Any changes you have
made (e.g., copied configuration files) will be lost. If you want to keep the
container, remove ``--rm=true`` from the command line.
You need to copy your OSSRH credentials and GnuPG keys to your docker container.
Run ``ifconfig`` in the host, find the IP address of the ``docker0`` interface.
Then in docker:
```
# scp -r <your-host-user>@<docker0-IP>:./.gnupg ~/
# mkdir ~/.gradle
# scp -r <your-host-user>@<docker0-IP>:./.gradle/gradle.properties ~/.gradle
```
Since ``$HOME`` is ``/root`` in the Docker container, remember to update
``signing.secretKeyRingFile`` in the Docker copy of ``gradle.properties`` to
point to ``/root/.gnupg/secring.gpg``
#### Windows 64-bit with MSYS2
##### Under MinGW-w64 Win32 Shell
```
grpc-java$ export CXXFLAGS="-I$HOME/protobuf-32/include" \
LDFLAGS="-L$HOME/protobuf-32/lib"
```
##### Under MinGW-w64 Win64 Shell
```
grpc-java$ export CXXFLAGS="-I$HOME/protobuf-64/include" \
LDFLAGS="-L$HOME/protobuf-64/lib"
```
#### Mac
```
grpc-java$ export CXXFLAGS="-I$HOME/protobuf/include" \
LDFLAGS="$HOME/protobuf/lib/libprotobuf.a $HOME/protobuf/lib/libprotoc.a"
```
### Deploy the Entire Project
The following command will build the whole project and upload it to Maven
Central.
```
grpc-java$ ./gradlew clean build && ./gradlew 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 OS you run on
it and the architecture of your JVM. For a fully fledged deployment, you will
need to deploy the codegen for all other supported OSes and architectures.
To deploy the codegen for an OS and architecture, you must run the following
commands on that OS and specify the architecture by the flag ``-PtargetArch=<arch>``.
We currently distribute the following OSes and architectures:
- Linux: ``x86_32``, ``x86_64``
- Windows: ``x86_32``, ``x86_64``
- Mac: ``x86_64``
If you are doing a snapshot deployment:
```
grpc-java$ ./gradlew clean grpc-compiler:build grpc-compiler:uploadArchives -PtargetArch=<arch>
```
If you are doing a release deployment:
```
grpc-java$ ./gradlew clean grpc-compiler:build grpc-compiler:uploadArchives -PtargetArch=<arch> \
-PrepositoryId=<repository-id>
```
where ``<repository-id>`` 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.

290
RELEASING.md Normal file
View File

@ -0,0 +1,290 @@
How to Create a Release of GRPC Java (for Maintainers Only)
===============================================================
Build Environments
------------------
We deploy GRPC to Maven Central under the following systems:
- Ubuntu 14.04 with Docker 1.6.1 that runs CentOS 6.6
- 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 (OSS Repository Hosting) 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). You'll also
need to [publish your public key](https://www.gnupg.org/gph/en/manual.html#AEN464)
to make it visible to the Sonatype servers
(e.g. `gpg --keyserver pgp.mit.edu --send-key <key ID>`).
- Put your GnuPG key password and OSSRH account information in
`<your-home-directory>/.gradle/gradle.properties`.
```
# You need the signing properties only if you are making release deployment
signing.keyId=<8-character-public-key-id>
signing.password=<key-password>
signing.secretKeyRingFile=<your-home-directory>/.gnupg/secring.gpg
ossrhUsername=<ossrh-username>
ossrhPassword=<ossrh-password>
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.
Please see the [Main Readme](README.md) for details on building protobuf.
Tagging the Release
----------------------
The first step in the release process is to create a release branch and then
from it, create a tag for the release. Our release branches follow the naming
convention of `v<major>.<minor>.x`, while the tags include the patch version
`v<major>.<minor>.<patch>`. For example, the same branch `v0.7.x`
would be used to create all `v0.7` tags (e.g. `v0.7.0`, `v0.7.1`).
1. Create the release branch:
```bash
$ git checkout -b v<major>.<minor>.x master
```
2. Next, increment the version in `build.gradle` in `master` to the next
minor snapshot (e.g. ``0.8.0-SNAPSHOT``).
3. In the release branch, change the `build.gradle` to the next release version
(e.g. `0.7.0`)
4. Push the release branch to github
```bash
$ git push upstream v<major>.<minor>.x
```
5. In the release branch, create the release tag using the `Major.Minor.Patch`
naming convention:
```bash
$ git tag -a v<major>.<minor>.<patch>
```
6. Push the release tag to github:
```bash
$ git push upstream v<major>.<minor>.<patch>
```
7. Update the `build.gradle` in the release branch to point to the next patch
snapshot (e.g. `0.7.1-SNAPSHOT`).
8. Push the updated release branch to github.
```bash
$ git push upstream v<major>.<minor>.x
```
Setup Build Environment
---------------------------
### Linux
The deployment for Linux uses [Docker](https://www.docker.com/) running
CentOS 6.6 in order to ensure that we have a consistent deployment environment
on Linux. You'll first need to install Docker if not already installed on your
system.
1. Under the [Protobuf source directory](https://github.com/google/protobuf),
build the `protoc-artifacts` image:
```bash
protobuf$ docker build -t protoc-artifacts protoc-artifacts
```
2. Under the grpc-java source directory, build the `grpc-java-deploy` image:
```bash
grpc-java$ docker build -t grpc-java-deploy compiler
```
3. Start a Docker container that has the deploy environment set up for you. The
GRPC source is cloned into `/grpc-java`.
```bash
$ docker run -it --rm=true grpc-java-deploy
```
Note that the container will be deleted after you exit. Any changes you have
made (e.g., copied configuration files) will be lost. If you want to keep the
container, remove `--rm=true` from the command line.
4. Next, you'll need to copy your OSSRH credentials and GnuPG keys to your docker container.
Run `ifconfig` in the host, find the IP address of the `docker0` interface.
Then in Docker:
```bash
$ scp -r <your-host-user>@<docker0-IP>:./.gnupg ~/
$ mkdir ~/.gradle
$ scp -r <your-host-user>@<docker0-IP>:./.gradle/gradle.properties ~/.gradle
```
You'll also need to update `signing.secretKeyRingFile` in
`/root/.gradle/gradle.properties` to point to `/root/.gnupg/secring.gpg`.
### Windows
#### 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
1. Compile and install 32-bit protobuf:
```bash
protobuf$ ./configure --disable-shared --prefix=$HOME/protobuf-32
protobuf$ make clean && make && make install
```
2. Configure CXXFLAGS needed by the protoc plugin when building.
```bash
grpc-java$ export CXXFLAGS="-I$HOME/protobuf-32/include" \
LDFLAGS="-L$HOME/protobuf-32/lib"
```
##### Under MinGW-w64 Win64 Shell
1. Compile and install 64-bit protobuf:
```bash
protobuf$ ./configure --disable-shared --prefix=$HOME/protobuf-64
protobuf$ make clean && make && make install
```
2. Configure CXXFLAGS needed by the protoc plugin when building.
```bash
grpc-java$ export CXXFLAGS="-I$HOME/protobuf-64/include" \
LDFLAGS="-L$HOME/protobuf-64/lib"
```
#### 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.
1. Compile and install 32-bit protobuf. `-static-libgcc -static-libstdc++` are
needed for `protoc` to be successfully run in the unit test.
```bash
protobuf$ LDFLAGS="-static-libgcc -static-libstdc++" ./configure --host=i686-w64-mingw32 --disable-shared --prefix=$HOME/protobuf-32
protobuf$ make clean && make && make install
```
2. Compile and install 64-bit protobuf:
```bash
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.
1. Compile and install protobuf:
```bash
protobuf$ CXXFLAGS="-m64" ./configure --disable-shared --prefix=$HOME/protobuf
protobuf$ make clean && make && make install
```
2. Configure CXXFLAGS needed by the protoc plugin when building.
```bash
grpc-java$ export CXXFLAGS="-I$HOME/protobuf/include" \
LDFLAGS="$HOME/protobuf/lib/libprotobuf.a $HOME/protobuf/lib/libprotoc.a"
```
Build and Deploy
----------------
We currently distribute the following OSes and architectures:
| OS | x86_32 | x86_64 |
| --- | --- | --- |
| Linux | X | X |
| Windows | X | X |
| Mac | | X |
Deployment to Maven Central (or the snapshot repo) is a two-step process. The only
artifact that is platform-specific is codegen, so we only need to deploy the other
jars once. So the first deployment is for all of the artifacts from one of the selected
OS/architectures. After that, we then deploy the codegen artifacts for the remaining
OS/architectures.
**NOTE: _Before building/deploying, be sure to switch to the appropriate branch or tag in
the grpc-java source directory._**
### First Deployment
As stated above, this only needs to be done once for one of the selected OS/architectures.
The following command will build the whole project and upload it to Maven
Central.
```bash
grpc-java$ ./gradlew clean build && ./gradlew 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 OS you run on
it and the architecture of your JVM. For a fully fledged deployment, you will
need to deploy the codegen for all other supported OSes and architectures.
To deploy the codegen for an OS and architecture, you must run the following
commands on that OS and specify the architecture by the flag `-PtargetArch=<arch>`.
If you are doing a snapshot deployment:
```bash
grpc-java$ ./gradlew clean grpc-compiler:build grpc-compiler:uploadArchives -PtargetArch=<arch>
```
When deploying a Release, the first deployment will create
[a new staging repository](https://oss.sonatype.org/#stagingRepositories). You'll need
to look up the ID in the OSSRH UI (usually in the form of `iogrpc-*`). Codegen
deployment commands should include `-PrepositoryId=<repository-id>` in order to
ensure that the artifacts are pushed to the same staging repository.
```bash
grpc-java$ ./gradlew clean grpc-compiler:build grpc-compiler:uploadArchives -PtargetArch=<arch> \
-PrepositoryId=<repository-id>
```
Releasing on Maven Central
--------------------------
Once all of the artifacts have been pushed to the staging repository, the
repository must first be `closed`, which will trigger several sanity checks
on the repository. If this completes successfully, the repository can then
be `released`, which will begin the process of pushing the new artifacts to
Maven Central (the staging repository will be destroyed in the process). You can
see the complete process for releasing to Maven Central on the [OSSRH site]
(http://central.sonatype.org/pages/releasing-the-deployment.html).
Notify the Community
--------------------
After waiting ~1 day and verifying that the release appears on [Maven Central]
(http://mvnrepository.com/), the last step is to document and publicize the release.
1. Add [Release Notes](https://github.com/grpc/grpc-java/releases) for the new tag.
The description should include any major fixes or features since the last release.
You may choose to add links to bugs, PRs, or commits if appropriate.
2. Post a release announcement to [grpc-io](https://groups.google.com/forum/#!forum/grpc-io)
(`grpc-io@googlegroups.com`). The title should be something that clearly identifies
the release (e.g.`GRPC-Java <tag> Released`).

6
compiler/README.md
View File

@ -51,6 +51,6 @@ repostiories.
$ ../gradlew install $ ../gradlew install
``` ```
## Pushing the codegen to Maven Central ## Creating a release of GRPC Java
Please follow the instructions in ``DEPLOYING.md`` under the root directory for Please follow the instructions in ``RELEASING.md`` under the root directory for
deploying the codegen to Maven Central. details on how to create a new release.