## How to generate a client library from a Protocol Buffers definition
## Install protoc with the gRPC plugin
First install v3 of the Protocol Buffers compiler (_protoc_), by cloning [its Git repository](https://github.com/google/protobuf) and following these [installation instructions](https://github.com/google/protobuf#c-installation---unix) (the ones titled C++; don't miss the note for Mac users).
On Mac OS X, install [homebrew][]. On Linux, install [linuxbrew][].
Then clone this repository and execute the following commands from the root directory where it was cloned.
Run the following command to install the Protocol Buffers compiler (_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.
## Use protoc to generate a gRPC library
Run _protoc_ with the following flags to generate the client library for your `.proto` files:
Compile the gRPC plugins for _protoc_:
```sh
make plugins
protoc --objc_out=. --objcgrpc_out=. *.proto
```
Create a symbolic link to the compiled plugin binary somewhere in your `$PATH`:
This will generate a pair of `.pbobjc.h`/`.pbobjc.m` files for each `.proto` file, with the messages and enums defined in them. And a pair of `.pbrpc.h`/`.pbrpc.m` files for each `.proto` file with services defined. The latter contains the code to make remote calls to the specified API.
## Integrate the generated gRPC library in your project
You need to create a Podspec file for the generated library. You may simply copy the following example to the directory where the source files were generated, updating the name and other metadata of the Podspec as necessary:
```ruby
Pod::Spec.new do |s|
s.name = '<Podspecfilename>'
s.version = '...'
s.summary = 'Client library to make RPCs to <myprotoAPI>'
s.homepage = '...'
s.license = '...'
s.authors = { '<myname>' => '<myemail>' }
s.ios.deployment_target = '6.0'
s.osx.deployment_target = '10.8'
s.subspec 'Messages' do |ms|
ms.source_files = '*.pbobjc.{h,m}'
ms.requires_arc = false
ms.dependency 'Protobuf', '~> 3.0'
end
s.subspec 'Services' do |ss|
ss.source_files = '*.pbrpc.{h,m}'
ss.requires_arc = true
ss.dependency 'gRPC', '~> 0.0'
ss.dependency '<Podspecfilename>/Messages'
end
end
```
The file should be named `<Podspec file name>.podspec`. You can refer to this [example Podspec][]. Once your library has a Podspec, Cocoapods can install it into any XCode project. For that, go into your project's directory and create a Podfile by running:
(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 _protoc_, in which case no system modification nor renaming is necessary.
Next add a line to your Podfile to refer to your library's Podspec. Use `:path` as described [here](https://guides.cocoapods.org/using/the-podfile.html#using-the-files-from-a-folder-local-to-the-machine):
```ruby
pod '<Podspecfilename>', :path => 'path/to/the/directory/of/your/podspec'
```
Finally, run _protoc_ with the following flags to generate the client library for your `.proto` files:
You can look at this [example Podfile][].
Finally, in your project's directory, run:
```sh
protoc --objc_out=. --objcgrpc_out=. *.proto
pod install
```
This will generate a pair of `.pbobjc.h`/`.pbobjc.m` files for each `.proto` file, with the messages and enums defined in them. And a pair of `.pbrpc.h`/`.pbrpc.m` files for each `.proto` file with services defined. The latter contains the code to make remote calls to the specified API.
## Use the generated library in your code
## How to integrate a generated gRPC library in your project
Please check this [sample app][] for examples of how to use a generated gRPC library.
### If you use Cocoapods
## Alternative methods
This is the recommended approach.
### Install protoc and the gRPC plugin without using Homebrew
You need to create a Podspec file for the generated library. This is simply a matter of copying an example like [this one](https://github.com/grpc/grpc/blob/master/src/objective-c/examples/Sample/RemoteTestClient/RemoteTest.podspec) to the directory where the source files were generated. Update the name and other metadata of the Podspec as suitable.
First install v3 of the Protocol Buffers compiler (_protoc_), by cloning [its Git repository](https://github.com/google/protobuf) and following these [installation instructions](https://github.com/google/protobuf#c-installation---unix) (the ones titled C++; don't miss the note for Mac users).
Once your library has a Podspec, refer to it from your Podfile using `:path` as described [here](https://guides.cocoapods.org/using/the-podfile.html#using-the-files-from-a-folder-local-to-the-machine).
Then clone this repository and execute the following commands from the root directory where it was cloned.
### If you don't use Cocoapods
Compile the gRPC plugins for _protoc_:
```sh
make plugins
```
Create a symbolic link to the compiled plugin binary somewhere in your `$PATH`:
(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 _protoc_, in which case no system modification nor renaming is necessary.
### Integrate the generated gRPC library without using Cocoapods
You need to compile the generated `.pbpbjc.*` files (the enums and messages) without ARC support, and the generated `.pbrpc.*` files (the services) with ARC support. The generated code depends on v0.3+ of the Objective-C gRPC runtime library and v3.0+ of the Objective-C Protobuf runtime library.
@ -45,3 +106,10 @@ These libraries need to be integrated into your project as described in their re
* [Podspec](https://github.com/grpc/grpc/blob/master/gRPC.podspec) for the Objective-C gRPC runtime library. This can be tedious to configure manually.
* [Podspec](https://github.com/jcanizales/protobuf/blob/add-podspec/Protobuf.podspec) for the Objective-C Protobuf runtime library.
Jorge Canizales
10 years ago