From 45bb7f36b452fa2f7f5eb1f9632476c50c7d4f5e Mon Sep 17 00:00:00 2001 From: Jorge Canizales Date: Mon, 11 Jul 2016 11:09:59 -0700 Subject: Use the deployed protoc spec in samples and README --- src/objective-c/README.md | 109 ++++++++++++++++++++++++++++++---------------- 1 file changed, 72 insertions(+), 37 deletions(-) (limited to 'src/objective-c') diff --git a/src/objective-c/README.md b/src/objective-c/README.md index 736c324ca9..a0ca5f448a 100644 --- a/src/objective-c/README.md +++ b/src/objective-c/README.md @@ -1,12 +1,12 @@ [![Cocoapods](https://img.shields.io/cocoapods/v/gRPC.svg)](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. - -## 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. - ## 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 = '/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 ## 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. ## 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. -## Alternative installation methods +## Alternatives to the steps above + + +### 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][]. -### 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 -- cgit v1.2.3