|
|
|
|
@ -1,12 +1,12 @@ |
|
|
|
|
[](https://cocoapods.org/pods/gRPC) |
|
|
|
|
# gRPC for Objective-C |
|
|
|
|
|
|
|
|
|
- [Install protoc with the gRPC plugin](#install) |
|
|
|
|
- [Write your API declaration in proto format](#write-protos) |
|
|
|
|
- [Integrate a proto library in your project](#cocoapods) |
|
|
|
|
- [Use the generated library in your code](#use) |
|
|
|
|
- [Use gRPC without Protobuf](#no-proto) |
|
|
|
|
- [Alternative installation methods](#alternatives) |
|
|
|
|
- [Alternatives to the steps above](#alternatives) |
|
|
|
|
- [Install protoc with the gRPC plugin](#install) |
|
|
|
|
- [Install protoc and the gRPC plugin without using Homebrew](#no-homebrew) |
|
|
|
|
- [Integrate the generated gRPC library without using Cocoapods](#no-cocoapods) |
|
|
|
|
|
|
|
|
|
@ -15,18 +15,6 @@ usage and adds some interoperability guarantees. Here we use [Protocol Buffers][ |
|
|
|
|
plugin for the Protobuf Compiler (_protoc_) to generate client libraries to communicate with gRPC |
|
|
|
|
services. |
|
|
|
|
|
|
|
|
|
<a name="install"></a> |
|
|
|
|
## Install protoc with the gRPC plugin |
|
|
|
|
|
|
|
|
|
On Mac OS X, install [homebrew][]. |
|
|
|
|
|
|
|
|
|
Run the following command to install _protoc_ and the gRPC _protoc_ plugin: |
|
|
|
|
```sh |
|
|
|
|
$ curl -fsSL https://goo.gl/getgrpc | bash - |
|
|
|
|
``` |
|
|
|
|
This will download and run the [gRPC install script][]. After the command completes, you're ready to |
|
|
|
|
proceed. |
|
|
|
|
|
|
|
|
|
<a name="write-protos"></a> |
|
|
|
|
## Write your API declaration in proto format |
|
|
|
|
|
|
|
|
|
@ -40,7 +28,8 @@ Install [Cocoapods](https://cocoapods.org/#install). |
|
|
|
|
|
|
|
|
|
You need to create a Podspec file for your proto library. You may simply copy the following example |
|
|
|
|
to the directory where your `.proto` files are located, updating the name, version and license as |
|
|
|
|
necessary: |
|
|
|
|
necessary. You also need to set the `pods_root` variable to the correct value, depending on where |
|
|
|
|
you place this podspec relative to your Podfile. |
|
|
|
|
|
|
|
|
|
```ruby |
|
|
|
|
Pod::Spec.new do |s| |
|
|
|
|
@ -55,16 +44,44 @@ Pod::Spec.new do |s| |
|
|
|
|
s.ios.deployment_target = '7.1' |
|
|
|
|
s.osx.deployment_target = '10.9' |
|
|
|
|
|
|
|
|
|
# Base directory where the .proto files are. |
|
|
|
|
src = '.' |
|
|
|
|
|
|
|
|
|
# We'll use protoc with the gRPC plugin. |
|
|
|
|
s.dependency '!ProtoCompiler-gRPCPlugin', '~> 0.14' |
|
|
|
|
|
|
|
|
|
# Pods directory corresponding to this app's Podfile, relative to the location of this podspec. |
|
|
|
|
pods_root = '<path to your Podfile>/Pods' |
|
|
|
|
|
|
|
|
|
# Path where Cocoapods downloads protoc and the gRPC plugin. |
|
|
|
|
protoc_dir = "#{pods_root}/!ProtoCompiler" |
|
|
|
|
protoc = "#{protoc_dir}/protoc" |
|
|
|
|
plugin = "#{pods_root}/!ProtoCompiler-gRPCPlugin/grpc_objective_c_plugin" |
|
|
|
|
|
|
|
|
|
# Directory where you want the generated files to be placed. This is an example. |
|
|
|
|
dir = "#{pods_root}/#{s.name}" |
|
|
|
|
|
|
|
|
|
# Run protoc with the Objective-C and gRPC plugins to generate protocol messages and gRPC clients. |
|
|
|
|
# You can run this command manually if you later change your protos and need to regenerate. |
|
|
|
|
s.prepare_command = "protoc --objc_out=. --objcgrpc_out=. *.proto" |
|
|
|
|
# Alternatively, you can advance the version of this podspec and run `pod update`. |
|
|
|
|
s.prepare_command = <<-CMD |
|
|
|
|
mkdir -p #{dir} |
|
|
|
|
#{protoc} \ |
|
|
|
|
--plugin=protoc-gen-grpc=#{plugin} \ |
|
|
|
|
--objc_out=#{dir} \ |
|
|
|
|
--grpc_out=#{dir} \ |
|
|
|
|
-I #{src} \ |
|
|
|
|
-I #{protoc_dir} \ |
|
|
|
|
#{src}/*.proto |
|
|
|
|
CMD |
|
|
|
|
|
|
|
|
|
# The --objc_out plugin generates a pair of .pbobjc.h/.pbobjc.m files for each .proto file. |
|
|
|
|
s.subspec "Messages" do |ms| |
|
|
|
|
ms.source_files = "*.pbobjc.{h,m}" |
|
|
|
|
ms.header_mappings_dir = "." |
|
|
|
|
s.subspec 'Messages' do |ms| |
|
|
|
|
ms.source_files = "#{dir}/*.pbobjc.{h,m}" |
|
|
|
|
ms.header_mappings_dir = dir |
|
|
|
|
ms.requires_arc = false |
|
|
|
|
ms.dependency "Protobuf", "~> 3.0.0-beta-2" |
|
|
|
|
# The generated files depend on the protobuf runtime. |
|
|
|
|
ms.dependency 'Protobuf' |
|
|
|
|
# This is needed by all pods that depend on Protobuf: |
|
|
|
|
ms.pod_target_xcconfig = { |
|
|
|
|
'GCC_PREPROCESSOR_DEFINITIONS' => '$(inherited) GPB_USE_PROTOBUF_FRAMEWORK_IMPORTS=1', |
|
|
|
|
@ -73,11 +90,12 @@ Pod::Spec.new do |s| |
|
|
|
|
|
|
|
|
|
# The --objcgrpc_out plugin generates a pair of .pbrpc.h/.pbrpc.m files for each .proto file with |
|
|
|
|
# a service defined. |
|
|
|
|
s.subspec "Services" do |ss| |
|
|
|
|
ss.source_files = "*.pbrpc.{h,m}" |
|
|
|
|
ss.header_mappings_dir = "." |
|
|
|
|
s.subspec 'Services' do |ss| |
|
|
|
|
ss.source_files = "#{dir}/*.pbrpc.{h,m}" |
|
|
|
|
ss.header_mappings_dir = dir |
|
|
|
|
ss.requires_arc = true |
|
|
|
|
ss.dependency "gRPC-ProtoRPC", "~> 0.14" |
|
|
|
|
# The generated files depend on the gRPC runtime, and on the files generated by `--objc_out`. |
|
|
|
|
ss.dependency 'gRPC-ProtoRPC' |
|
|
|
|
ss.dependency "#{s.name}/Messages" |
|
|
|
|
end |
|
|
|
|
end |
|
|
|
|
@ -89,11 +107,14 @@ Note: If your proto files are in a directory hierarchy, you might want to adjust |
|
|
|
|
the sample Podspec above. For example, you could use: |
|
|
|
|
|
|
|
|
|
```ruby |
|
|
|
|
s.prepare_command = "protoc --objc_out=. --objcgrpc_out=. *.proto **/*.proto" |
|
|
|
|
s.prepare_command = <<-CMD |
|
|
|
|
... |
|
|
|
|
#{src}/*.proto #{src}/**/*.proto |
|
|
|
|
CMD |
|
|
|
|
... |
|
|
|
|
ms.source_files = "*.pbobjc.{h,m}", "**/*.pbobjc.{h,m}" |
|
|
|
|
ms.source_files = "#{dir}/*.pbobjc.{h,m}", "#{dir}/**/*.pbobjc.{h,m}" |
|
|
|
|
... |
|
|
|
|
ss.source_files = "*.pbrpc.{h,m}", "**/*.pbrpc.{h,m}" |
|
|
|
|
ss.source_files = "#{dir}/*.pbrpc.{h,m}", "#{dir}/**/*.pbrpc.{h,m}" |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
Once your library has a Podspec, Cocoapods can install it into any XCode project. For that, go into |
|
|
|
|
@ -121,19 +142,33 @@ pod install |
|
|
|
|
<a name="use"></a> |
|
|
|
|
## Use the generated library in your code |
|
|
|
|
|
|
|
|
|
Please check this [sample app][] for examples of how to use a generated gRPC library. |
|
|
|
|
Please check the [example apps][] for examples of how to use a generated gRPC library. |
|
|
|
|
|
|
|
|
|
<a name="no-proto"></a> |
|
|
|
|
## Use gRPC without Protobuf |
|
|
|
|
|
|
|
|
|
The [sample app][] has an example of how to use the generic gRPC Objective-C client without |
|
|
|
|
generated files. |
|
|
|
|
This [tests file](https://github.com/grpc/grpc/tree/master/src/objective-c/tests/GRPCClientTests.m) |
|
|
|
|
shows how to use the generic gRPC Objective-C client without generated protobuf files. |
|
|
|
|
|
|
|
|
|
<a name="alternatives"></a> |
|
|
|
|
## Alternative installation methods |
|
|
|
|
## Alternatives to the steps above |
|
|
|
|
|
|
|
|
|
<a name="install"></a> |
|
|
|
|
### Install _protoc_ with the gRPC plugin |
|
|
|
|
|
|
|
|
|
Although it's not recommended (because it can lead to hard-to-solve version conflicts), it is |
|
|
|
|
sometimes more convenient to install _protoc_ and the gRPC plugin in your development machine, |
|
|
|
|
instead of letting Cocoapods download the appropriate versions for you. To do so, on Mac OS X or |
|
|
|
|
later, install [homebrew][]. |
|
|
|
|
|
|
|
|
|
The run the following command to install _protoc_ and the gRPC _protoc_ plugin: |
|
|
|
|
```sh |
|
|
|
|
$ curl -fsSL https://goo.gl/getgrpc | bash - |
|
|
|
|
``` |
|
|
|
|
This will download and run the [gRPC install script][]. |
|
|
|
|
|
|
|
|
|
<a name="no-homebrew"></a> |
|
|
|
|
### Install protoc and the gRPC plugin without using Homebrew |
|
|
|
|
### Install _protoc_ and the gRPC plugin without using Homebrew |
|
|
|
|
|
|
|
|
|
First install v3 of the Protocol Buffers compiler (_protoc_), by cloning |
|
|
|
|
[its Git repository](https://github.com/google/protobuf) and following these |
|
|
|
|
@ -145,15 +180,15 @@ cloned. |
|
|
|
|
|
|
|
|
|
Compile the gRPC plugins for _protoc_: |
|
|
|
|
```sh |
|
|
|
|
make plugins |
|
|
|
|
make grpc_objective_c_plugin |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
Create a symbolic link to the compiled plugin binary somewhere in your `$PATH`: |
|
|
|
|
```sh |
|
|
|
|
ln -s `pwd`/bins/opt/grpc_objective_c_plugin /usr/local/bin/protoc-gen-objcgrpc |
|
|
|
|
``` |
|
|
|
|
(Notice that the name of the created link must begin with "protoc-gen-" for _protoc_ to recognize it |
|
|
|
|
as a plugin). |
|
|
|
|
(Notice that the name of the created link must begin with "`protoc-gen-`" for _protoc_ to recognize |
|
|
|
|
it as a plugin). |
|
|
|
|
|
|
|
|
|
If you don't want to create the symbolic link, you can alternatively copy the binary (with the |
|
|
|
|
appropriate name). Or you might prefer instead to specify the plugin's path as a flag when invoking |
|
|
|
|
@ -178,5 +213,5 @@ Objective-C Protobuf runtime library. |
|
|
|
|
[Protocol Buffers]:https://developers.google.com/protocol-buffers/ |
|
|
|
|
[homebrew]:http://brew.sh |
|
|
|
|
[gRPC install script]:https://raw.githubusercontent.com/grpc/homebrew-grpc/master/scripts/install |
|
|
|
|
[example Podfile]:https://github.com/grpc/grpc/blob/master/src/objective-c/examples/Sample/Podfile |
|
|
|
|
[sample app]: https://github.com/grpc/grpc/tree/master/src/objective-c/examples/Sample |
|
|
|
|
[example Podfile]:https://github.com/grpc/grpc/blob/master/examples/objective-c/helloworld/Podfile |
|
|
|
|
[example apps]: https://github.com/grpc/grpc/tree/master/examples/objective-c |
|
|
|
|
|
Jorge Canizales
8 years ago