Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added additonal information for installation and usage to make setup … #347

Closed
wants to merge 1 commit into from
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 17 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,8 @@ That's what grpc-gateway helps you to do. You just need to implement your gRPC s
Then the reverse-proxy generated by grpc-gateway serves RESTful API on top of the gRPC service.

## Installation
First you need to install ProtocolBuffers 3.0.0-beta-3 or later.
First you need to install [golang](https://golang.org/dl) and ProtocolBuffers 3.0.0-beta-3 or later for your platform.
For ProtocolBuffers either download a pre-built [binary](https://github.com/google/protobuf/releases) for your platform or build it from source.

```sh
mkdir tmp
Expand All @@ -35,6 +36,8 @@ make
make check
sudo make install
```
If you are using cygwin and ProtocolBuffers 3.0.0-beta-3 or later is not available for cygwin yet install the Windows version.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

would it be appropriate to place windows instructions in its own section?

Make sure that `protoc.exe` is in your `$PATH` and copy the `include` directory from the windows binary into cygwin's `/usr/local/include` directory.

Then, `go get -u` as usual the following packages:

Expand Down Expand Up @@ -93,7 +96,12 @@ Make sure that your `$GOPATH/bin` is in your `$PATH`.
--go_out=plugins=grpc:. \
path/to/your_service.proto
```

If you are a using cygwin replace the first line in the following commands to provide the correct path to the include directory to `protoc`.
```diff
-protoc -I/usr/local/include -I. \
+protoc -I$(cygpath -w /usr/local/include) -I. \
```

It will generate a stub file `path/to/your_service.pb.go`.
4. Implement your service in gRPC as usual
1. (Optional) Generate gRPC stub in the language you want.
Expand Down Expand Up @@ -128,7 +136,7 @@ Make sure that your `$GOPATH/bin` is in your `$PATH`.

It will generate a reverse proxy `path/to/your_service.pb.gw.go`.

Note: After generating the code for each of the stubs, in order to build the code, you will want to run ```go get .``` from the directory containing the stubs.
Note: After generating the code for each of the stubs, in order to build the code, you will want to move the stubs into your `$GOPATH/src` working directory and run ```go get .``` from the directory containing the stubs.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

how about we recommend that folks work inside of GOPATH over moving files after gen?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the protoc command creates the stubs in the same directory as the service.proto file. is it possible to provide an output directory for the protoc plugins?


6. Write an entrypoint

Expand Down Expand Up @@ -186,6 +194,12 @@ Make sure that your `$GOPATH/bin` is in your `$PATH`.
--swagger_out=logtostderr=true:. \
path/to/your_service.proto
```
8. Generate executable

Run this inside the directory containg your `main.go`.
```
go build
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

let's recommend go install instead

```

## Parameters and flags
`protoc-gen-grpc-gateway` supports custom mapping from Protobuf `import` to Golang import path.
Expand Down