update README.md (#36)

- Adds a travis CI badge at the top.
- Adds an "installation" section that should address #30
- Adds content about using proto source files.

README.md

@@ -1,4 +1,6 @@
 # gRPCurl
+[![Build Status](https://travis-ci.org/fullstorydev/grpcurl.svg?branch=master)](https://travis-ci.org/fullstorydev/grpcurl/branches)
+
 `grpcurl` is a command-line tool that lets you interact with gRPC servers. It's
 basically `curl` for gRPC servers.
 
@@ -18,7 +20,9 @@ In fact, the way the tool transforms JSON request data into a binary encoded pro
 is using that very same schema. So, if the server you interact with does not support
 reflection, you will need to build "protoset" files that `grpcurl` can use.
 
-This code for this tool is also a great example of how to use the various packages of
+This repo also provides a library package, `github.com/fullstorydev/grpcurl`, that has
+functions for simplifying the construction of other command-line tools that dynamically
+invoke gRPC endpoints. This code is a great example of how to use the various packages of
 the [protoreflect](https://godoc.org/github.com/jhump/protoreflect) library, and shows
 off what they can do.
 
@@ -32,50 +36,95 @@ configuration. It also supports mutual TLS, where the client is required to pres
 client certificate.
 
 As mentioned above, `grpcurl` works seamlessly if the server supports the reflection
-service. If not, you must use `protoc` to build protoset files and provide those to
+service. If not, you can supply the `.proto` source files or you can supply protoset
-`grpcurl`.
+files (containing compiled descriptors, produced by `protoc`) to `grpcurl`.
+
+## Installation
+You can use the `go` tool to install `grpcurl`:
+```shell
+go get github.com/fullstorydev/grpcurl
+go install github.com/fullstorydev/grpcurl/cmd/grpcurl
+```
+
+This installs the command into the `bin` sub-folder of wherever your `$GOPATH`
+environment variable points. If this directory is already in your `$PATH`, then
+you should be good to go.
+
+If you have already pulled down this repo to a location that is not in your
+`$GOPATH` and want to build from the sources, you can `cd` into the repo and then
+run `make install`.
+
+If you encounter compile errors, you could have out-dated versions of `grpcurl`'s
+dependencies. You can update the dependencies by running `make updatedeps`.
 
 ## Example Usage
 Invoking an RPC on a trusted server (e.g. TLS without self-signed key or custom CA)
 that requires no client certs and supports service reflection is the simplest thing to
 do with `grpcurl`. This minimal invocation sends an empty request body:
-```
+```shell
 grpcurl grpc.server.com:443 my.custom.server.Service/Method
 ```
 
-To list all services exposed by a server, use the "list" verb. When using protoset files
+To list all services exposed by a server, use the "list" verb. When using `.proto` source
-instead of server reflection, this lists all services defined in the protoset files.
+or protoset files instead of server reflection, this lists all services defined in the
-```
+source or protoset files.
+```shell
+# Server supports reflection
 grpcurl localhost:8787 list
 
+# Using compiled protoset files
 grpcurl -protoset my-protos.bin list
+
+# Using proto sources
+grpcurl -import-path ../protos -proto my-stuff.proto list
 ```
 
 The "list" verb also lets you see all methods in a particular service:
-```
+```shell
 grpcurl localhost:8787 list my.custom.server.Service
 ```
 
 The "describe" verb will print the type of any symbol that the server knows about
 or that is found in a given protoset file and also print the full descriptor for the
 symbol, in JSON.
-```
+```shell
+# Server supports reflection
 grpcurl localhost:8787 describe my.custom.server.Service.MethodOne
 
+# Using compiled protoset files
 grpcurl -protoset my-protos.bin describe my.custom.server.Service.MethodOne
+
+# Using proto sources
+grpcurl -import-path ../protos -proto my-stuff.proto describe my.custom.server.Service.MethodOne
 ```
 
 The usage doc for the tool explains the numerous options:
-```
+```shell
 grpcurl -help
 ```
 
-## Protoset Files
+## Proto Source Files
-To use `grpcurl` on servers that do not support reflection, you need to compile the
+To use `grpcurl` on servers that do not support reflection, you can use `.proto` source
-`*.proto` files that describe the service into files containing encoded
+files.
-`FileDescriptorSet` protos, also known as "protoset" files.
 
-```
+In addition to using `-proto` flags to point `grpcurl` at the relevant proto source file(s),
+you may also need to supply `-import-path` flags to tell `grpcurl` the folders from which
+dependencies can be imported.
+
+Just like when compiling with `protoc`, you do *not* need to provide an import path for the
+location of the standard protos included with `protoc` (which contain various "well-known
+types" with a package definition of `google.protobuf`). These files are "known" by `grpcurl`
+as a snapshot of their descriptors is built into the `grpcurl` binary.
+
+## Protoset Files
+You can also use compiled protoset files with `grpcurl`. If you are scripting `grpcurl` and
+need to re-use the same proto sources for many invocations, you will see better performance
+by using protoset files (since it skips the parsing and compilation steps with each
+invocation).
+
+Protoset files contain binary encoded `google.protobuf.FileDescriptorSet` protos. To create
+a protoset file, invoke `protoc` with the `*.proto` files that describe the service:
+```shell
 protoc --proto_path=. \
     --descriptor_set_out=myservice.protoset \
     --include_imports \
@@ -83,5 +132,5 @@ protoc --proto_path=. \
 ```
 
 The `--descriptor_set_out` argument is what tells `protoc` to produce a protoset,
-and the `--include_imports` arguments is necessary for the protoset to contain
+and the `--include_imports` argument is necessary for the protoset to contain
 everything that `grpcurl` needs to process and understand the schema.