| Up to higher level directory | |||
| Name | Date | Size | |
|---|---|---|---|
| !ProtoCompiler-gRPCPlugin.podspec | 22-Oct-2020 | 6K | |
| !ProtoCompiler.podspec | 22-Oct-2020 | 6.4K | |
| BoringSSL-GRPC.podspec | 22-Oct-2020 | 241.6K | |
| change-comments.py | 22-Oct-2020 | 2.6K | |
| CronetFramework.podspec | 22-Oct-2020 | 3.8K | |
| examples/ | 22-Oct-2020 | ||
| format-all-comments.sh | 22-Oct-2020 | 742 | |
| grpc_shadow_boringssl_symbol_list | 22-Oct-2020 | 57.1K | |
| GRPCClient/ | 22-Oct-2020 | ||
| NetworkTransitionBehavior.md | 22-Oct-2020 | 5.1K | |
| ProtoRPC/ | 22-Oct-2020 | ||
| README-CFSTREAM.md | 22-Oct-2020 | 1.6K | |
| README.md | 22-Oct-2020 | 9.7K | |
| RxLibrary/ | 22-Oct-2020 | ||
| tests/ | 22-Oct-2020 | ||
README-CFSTREAM.md
1 [](https://cocoapods.org/pods/gRPC) 2 # gRPC Objective-C with CFStream 3 4 gRPC Objective-C library now provides the option to use Apple's CFStream API (rather than TCP 5 sockets) for networking. Using CFStream resolves a bunch of network connectivity transition issues 6 (see the [doc](https://github.com/grpc/grpc/blob/master/src/objective-c/NetworkTransitionBehavior.md) 7 for more information). 8 9 CFStream integration is now in experimental state. You will need explicit opt-in to use it to get 10 the benefits of resolving the issues above. We expect to make CFStream the default networking 11 interface that gRPC uses when it is ready for production. 12 13 ## Usage 14 If you use gRPC following the instructions in 15 [README.md](https://github.com/grpc/grpc/blob/master/src/objective-c/README.md): 16 - Replace the 17 dependency on `gRPC-ProtoRPC` with `gRPC-ProtoRPC/CFStream`. 18 - Enable CFStream with environment variable `grpc_cfstream=1`. This can be done either in Xcode 19 console or by your code with `setenv()` before gRPC is initialized. 20 21 If your project directly depends on podspecs other than `gRPC-ProtoRPC` (e.g. `gRPC` or 22 `gRPC-Core`): 23 24 - Make your projects depend on subspecs corresponding to CFStream in each gRPC podspec. 25 - Enable CFStream with environment variable `grpc_cfstream=1`. This can be done either in Xcode 26 console or by your code with `setenv()` before gRPC is initialized. 27 28 ## Notes 29 30 - Currently we do not support platforms other than iOS, although it is likely that this integration 31 can run on MacOS targets with Apple's compiler. 32 - Let us know if you meet any issue by filing issue and ping @muxi. 33
README.md
1 [](https://cocoapods.org/pods/gRPC) 2 # gRPC for Objective-C 3 gRPC Objective C library provides Objective C API for users to make gRPC calls on iOS or OS X 4 platforms. Currently, the minimum supported iOS version is 7.0 and OS X version is 10.9 (Mavericks). 5 6 While gRPC doesn't require the use of an IDL to describe the API of services, using one simplifies 7 usage and adds some interoperability guarantees. Here we use [Protocol Buffers][], and provide a 8 plugin for the Protobuf Compiler (_protoc_) to generate client libraries to communicate with gRPC 9 services. 10 11 - [Write your API declaration in proto format](#write-protos) 12 - [Integrate a proto library in your project](#cocoapods) 13 - [Use the generated library in your code](#use) 14 - [Use gRPC without Protobuf](#no-proto) 15 - [Alternatives to the steps above](#alternatives) 16 - [Install protoc with the gRPC plugin](#install) 17 - [Install protoc and the gRPC plugin without using Homebrew](#no-homebrew) 18 - [Integrate the generated gRPC library without using Cocoapods](#no-cocoapods) 19 20 <a name="write-protos"></a> 21 ## Write your API declaration in proto format 22 23 For this you can consult the [Protocol Buffers][]' official documentation, or learn from a quick 24 example [here](https://github.com/grpc/grpc/tree/master/examples#defining-a-service). 25 26 <a name="cocoapods"></a> 27 ## Integrate a proto library in your project 28 29 Install [Cocoapods](https://cocoapods.org/#install). 30 31 You need to create a Podspec file for your proto library. You may simply copy the following example 32 to the directory where your `.proto` files are located, updating the name, version and license as 33 necessary. You also need to set the `pods_root` variable to the correct value, depending on where 34 you place this podspec relative to your Podfile. 35 36 ```ruby 37 Pod::Spec.new do |s| 38 s.name = '<Podspec file name>' 39 s.version = '0.0.1' 40 s.license = '...' 41 s.authors = { '<your name>' => '<your email>' } 42 s.homepage = '...' 43 s.summary = '...' 44 s.source = { :git => 'https://github.com/...' } 45 46 s.ios.deployment_target = '7.1' 47 s.osx.deployment_target = '10.9' 48 49 # Base directory where the .proto files are. 50 src = '.' 51 52 # We'll use protoc with the gRPC plugin. 53 s.dependency '!ProtoCompiler-gRPCPlugin', '~> 1.0' 54 55 # Pods directory corresponding to this app's Podfile, relative to the location of this podspec. 56 pods_root = '<path to your Podfile>/Pods' 57 58 # Path where Cocoapods downloads protoc and the gRPC plugin. 59 protoc_dir = "#{pods_root}/!ProtoCompiler" 60 protoc = "#{protoc_dir}/protoc" 61 plugin = "#{pods_root}/!ProtoCompiler-gRPCPlugin/grpc_objective_c_plugin" 62 63 # Directory where you want the generated files to be placed. This is an example. 64 dir = "#{pods_root}/#{s.name}" 65 66 # Run protoc with the Objective-C and gRPC plugins to generate protocol messages and gRPC clients. 67 # You can run this command manually if you later change your protos and need to regenerate. 68 # Alternatively, you can advance the version of this podspec and run `pod update`. 69 s.prepare_command = <<-CMD 70 mkdir -p #{dir} 71 #{protoc} \ 72 --plugin=protoc-gen-grpc=#{plugin} \ 73 --objc_out=#{dir} \ 74 --grpc_out=#{dir} \ 75 -I #{src} \ 76 -I #{protoc_dir} \ 77 #{src}/*.proto 78 CMD 79 80 # The --objc_out plugin generates a pair of .pbobjc.h/.pbobjc.m files for each .proto file. 81 s.subspec 'Messages' do |ms| 82 ms.source_files = "#{dir}/*.pbobjc.{h,m}" 83 ms.header_mappings_dir = dir 84 ms.requires_arc = false 85 # The generated files depend on the protobuf runtime. 86 ms.dependency 'Protobuf' 87 end 88 89 # The --objcgrpc_out plugin generates a pair of .pbrpc.h/.pbrpc.m files for each .proto file with 90 # a service defined. 91 s.subspec 'Services' do |ss| 92 ss.source_files = "#{dir}/*.pbrpc.{h,m}" 93 ss.header_mappings_dir = dir 94 ss.requires_arc = true 95 # The generated files depend on the gRPC runtime, and on the files generated by `--objc_out`. 96 ss.dependency 'gRPC-ProtoRPC' 97 ss.dependency "#{s.name}/Messages" 98 end 99 100 s.pod_target_xcconfig = { 101 # This is needed by all pods that depend on Protobuf: 102 'GCC_PREPROCESSOR_DEFINITIONS' => '$(inherited) GPB_USE_PROTOBUF_FRAMEWORK_IMPORTS=1', 103 # This is needed by all pods that depend on gRPC-RxLibrary: 104 'CLANG_ALLOW_NON_MODULAR_INCLUDES_IN_FRAMEWORK_MODULES' => 'YES', 105 } 106 end 107 ``` 108 109 The file should be named `<Podspec file name>.podspec`. 110 111 Note: If your proto files are in a directory hierarchy, you might want to adjust the _globs_ used in 112 the sample Podspec above. For example, you could use: 113 114 ```ruby 115 s.prepare_command = <<-CMD 116 ... 117 `find . -name *.proto -print | xargs` 118 CMD 119 ... 120 ms.source_files = "#{dir}/*.pbobjc.{h,m}", "#{dir}/**/*.pbobjc.{h,m}" 121 ... 122 ss.source_files = "#{dir}/*.pbrpc.{h,m}", "#{dir}/**/*.pbrpc.{h,m}" 123 ``` 124 125 Once your library has a Podspec, Cocoapods can install it into any XCode project. For that, go into 126 your project's directory and create a Podfile by running: 127 128 ```sh 129 pod init 130 ``` 131 132 Next add a line to your Podfile to refer to your library's Podspec. Use `:path` as described 133 [here](https://guides.cocoapods.org/using/the-podfile.html#using-the-files-from-a-folder-local-to-the-machine): 134 135 ```ruby 136 pod '<Podspec file name>', :path => 'path/to/the/directory/of/your/podspec' 137 ``` 138 139 You can look at this [example Podfile][]. 140 141 Finally, in your project's directory, run: 142 143 ```sh 144 pod install 145 ``` 146 147 <a name="use"></a> 148 ## Use the generated library in your code 149 150 Please check the [example apps][] for examples of how to use a generated gRPC library. 151 152 <a name="no-proto"></a> 153 ## Use gRPC without Protobuf 154 155 This [tests file](https://github.com/grpc/grpc/tree/master/src/objective-c/tests/GRPCClientTests.m) 156 shows how to use the generic gRPC Objective-C client without generated protobuf files. 157 158 <a name="alternatives"></a> 159 ## Alternatives to the steps above 160 161 <a name="install"></a> 162 ### Install _protoc_ with the gRPC plugin 163 164 Although it's not recommended (because it can lead to hard-to-solve version conflicts), it is 165 sometimes more convenient to install _protoc_ and the gRPC plugin in your development machine, 166 instead of letting Cocoapods download the appropriate versions for you. To do so, on Mac OS X or 167 later, install [homebrew][]. 168 169 The run the following command to install _protoc_ and the gRPC _protoc_ plugin: 170 ```sh 171 $ curl -fsSL https://goo.gl/getgrpc | bash - 172 ``` 173 This will download and run the [gRPC install script][]. 174 175 <a name="no-homebrew"></a> 176 ### Install _protoc_ and the gRPC plugin without using Homebrew 177 178 First install v3 of the Protocol Buffers compiler (_protoc_), by cloning 179 [its Git repository](https://github.com/google/protobuf) and following these 180 [installation instructions](https://github.com/google/protobuf#c-installation---unix) 181 (the ones titled C++; don't miss the note for Mac users). 182 183 Then clone this repository and execute the following commands from the root directory where it was 184 cloned. 185 186 Compile the gRPC plugins for _protoc_: 187 ```sh 188 make grpc_objective_c_plugin 189 ``` 190 191 Create a symbolic link to the compiled plugin binary somewhere in your `$PATH`: 192 ```sh 193 ln -s `pwd`/bins/opt/grpc_objective_c_plugin /usr/local/bin/protoc-gen-objcgrpc 194 ``` 195 (Notice that the name of the created link must begin with "`protoc-gen-`" for _protoc_ to recognize 196 it as a plugin). 197 198 If you don't want to create the symbolic link, you can alternatively copy the binary (with the 199 appropriate name). Or you might prefer instead to specify the plugin's path as a flag when invoking 200 _protoc_, in which case no system modification nor renaming is necessary. 201 202 <a name="no-cocoapods"></a> 203 ### Integrate the generated gRPC library without using Cocoapods 204 205 You need to compile the generated `.pbobjc.*` files (the enums and messages) without ARC support, 206 and the generated `.pbrpc.*` files (the services) with ARC support. The generated code depends on 207 v0.12+ of the Objective-C gRPC runtime library and v3.0.0-alpha-4+ of the Objective-C Protobuf 208 runtime library. 209 210 These libraries need to be integrated into your project as described in their respective Podspec 211 files: 212 213 * [Podspec](https://github.com/grpc/grpc/blob/master/gRPC.podspec) for the Objective-C gRPC runtime 214 library. This can be tedious to configure manually. 215 * [Podspec](https://github.com/google/protobuf/blob/master/Protobuf.podspec) for the 216 Objective-C Protobuf runtime library. 217 218 [Protocol Buffers]:https://developers.google.com/protocol-buffers/ 219 [homebrew]:http://brew.sh 220 [gRPC install script]:https://raw.githubusercontent.com/grpc/homebrew-grpc/master/scripts/install 221 [example Podfile]:https://github.com/grpc/grpc/blob/master/examples/objective-c/helloworld/Podfile 222 [example apps]: https://github.com/grpc/grpc/tree/master/examples/objective-c 223 224 ## Use gRPC with OpenSSL 225 gRPC uses BoringSSL as its dependency, which is a fork of OpenSSL and export a number of symbols 226 that are the same as OpenSSL. gRPC avoids conflicts of these symbols by renaming BoringSSL symbols. 227 228 If you need gRPC to use OpenSSL instead of BoringSSL (e.g. for the benefit of reducing the binary 229 size of your product), you need to make a local `gRPC-Core` podspec and tweak it accordingly: 230 - Copy the version of `/gRPC-Core.podspec` you wish to use from Github into the repository of your 231 app; 232 - In your `Podfile`, add the following line: 233 ``` 234 pod `gRPC-Core`, :podspec => "." # assuming gRPC-Core.podspec is in the same directory as your Podfile 235 ``` 236 - Remove [the 237 macro](https://github.com/grpc/grpc/blob/b24b212ee585d376c618235905757b2445ac6461/gRPC-Core.podspec#L186) 238 `GRPC_SHADOW_BORINGSSL_SYMBOLS` to disable symbol renaming; 239 - Substitude the `BoringSSL-GRPC` 240 [dependency](https://github.com/grpc/grpc/blob/b24b212ee585d376c618235905757b2445ac6461/gRPC-Core.podspec#L184) 241 to whatever pod of OpenSSL your other libraries use. 242 243 These steps should allow gRPC to use OpenSSL and drop BoringSSL dependency. If you see any issue, 244 file an issue to us. 245
