carto
/
grpc


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236
							<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.17"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>GRPC Objective-C: README</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">GRPC Objective-C
   &#160;<span id="projectnumber">1.36.1</span>
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.17 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

</div><!-- top -->
<div class="PageDoc"><div class="header">
  <div class="headertitle">
<div class="title">README </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p><a href="https://cocoapods.org/pods/gRPC"><object type="image/svg+xml" data="https://img.shields.io/cocoapods/v/gRPC.svg" style="pointer-events: none;">Cocoapods</object></a> </p>
<h1><a class="anchor" id="autotoc_md268"></a>
gRPC for Objective-C</h1>
<p>gRPC Objective C library provides Objective C API for users to make gRPC calls on iOS or OS X platforms. Currently, the minimum supported iOS version is 9.0 and OS X version is 10.10 (Yosemite).</p>
<p>While gRPC doesn't require the use of an IDL to describe the API of services, using one simplifies usage and adds some interoperability guarantees. Here we use <a href="https://developers.google.com/protocol-buffers/">Protocol Buffers</a>, and provide a plugin for the Protobuf Compiler (<em>protoc</em>) to generate client libraries to communicate with gRPC services.</p>
<ul>
<li><a href="#write-protos">Write your API declaration in proto format</a></li>
<li><a href="#cocoapods">Integrate a proto library in your project</a></li>
<li><a href="#use">Use the generated library in your code</a></li>
<li><a href="#no-proto">Use gRPC without Protobuf</a></li>
<li><a href="#alternatives">Alternatives to the steps above</a><ul>
<li><a href="#install">Install protoc with the gRPC plugin</a></li>
<li><a href="#no-homebrew">Install protoc and the gRPC plugin without using Homebrew</a></li>
<li><a href="#no-cocoapods">Integrate the generated gRPC library without using Cocoapods</a></li>
</ul>
</li>
</ul>
<p><a class="anchor" id="write-protos"></a> </p>
<h2><a class="anchor" id="autotoc_md269"></a>
Write your API declaration in proto format</h2>
<p>For this you can consult the <a href="https://developers.google.com/protocol-buffers/">Protocol Buffers</a>' official documentation, or learn from a quick example <a href="https://github.com/grpc/grpc/tree/master/examples#defining-a-service">here</a>.</p>
<p><a class="anchor" id="cocoapods"></a> </p>
<h2><a class="anchor" id="autotoc_md270"></a>
Integrate a proto library in your project</h2>
<p>Install <a href="https://cocoapods.org/#install">Cocoapods</a>.</p>
<p>You need to create a Podspec file for your proto library. You may simply copy the following example to the directory where your <code>.proto</code> files are located, updating the name, version and license as necessary. You also need to set the <code>pods_root</code> variable to the correct value, depending on where you place this podspec relative to your Podfile.</p>
<div class="fragment"><div class="line">Pod::Spec.new do |s|</div>
<div class="line">  s.name     = &#39;&lt;Podspec file name&gt;&#39;</div>
<div class="line">  s.version  = &#39;0.0.1&#39;</div>
<div class="line">  s.license  = &#39;...&#39;</div>
<div class="line">  s.authors  = { &#39;&lt;your name&gt;&#39; =&gt; &#39;&lt;your email&gt;&#39; }</div>
<div class="line">  s.homepage = &#39;...&#39;</div>
<div class="line">  s.summary = &#39;...&#39;</div>
<div class="line">  s.source = { :git =&gt; &#39;https://github.com/...&#39; }</div>
<div class="line"> </div>
<div class="line">  s.ios.deployment_target = &#39;9.0&#39;</div>
<div class="line">  s.osx.deployment_target = &#39;10.10&#39;</div>
<div class="line"> </div>
<div class="line">  # Base directory where the .proto files are.</div>
<div class="line">  src = &#39;.&#39;</div>
<div class="line"> </div>
<div class="line">  # We&#39;ll use protoc with the gRPC plugin.</div>
<div class="line">  s.dependency &#39;!ProtoCompiler-gRPCPlugin&#39;, &#39;~&gt; 1.0&#39;</div>
<div class="line"> </div>
<div class="line">  # Pods directory corresponding to this app&#39;s Podfile, relative to the location of this podspec.</div>
<div class="line">  pods_root = &#39;&lt;path to your Podfile&gt;/Pods&#39;</div>
<div class="line"> </div>
<div class="line">  # Path where Cocoapods downloads protoc and the gRPC plugin.</div>
<div class="line">  protoc_dir = &quot;#{pods_root}/!ProtoCompiler&quot;</div>
<div class="line">  protoc = &quot;#{protoc_dir}/protoc&quot;</div>
<div class="line">  plugin = &quot;#{pods_root}/!ProtoCompiler-gRPCPlugin/grpc_objective_c_plugin&quot;</div>
<div class="line"> </div>
<div class="line">  # Directory where you want the generated files to be placed. This is an example.</div>
<div class="line">  dir = &quot;#{pods_root}/#{s.name}&quot;</div>
<div class="line"> </div>
<div class="line">  # Run protoc with the Objective-C and gRPC plugins to generate protocol messages and gRPC clients.</div>
<div class="line">  # You can run this command manually if you later change your protos and need to regenerate.</div>
<div class="line">  # Alternatively, you can advance the version of this podspec and run `pod update`.</div>
<div class="line">  s.prepare_command = &lt;&lt;-CMD</div>
<div class="line">    mkdir -p #{dir}</div>
<div class="line">    #{protoc} \</div>
<div class="line">        --plugin=protoc-gen-grpc=#{plugin} \</div>
<div class="line">        --objc_out=#{dir} \</div>
<div class="line">        --grpc_out=#{dir} \</div>
<div class="line">        -I #{src} \</div>
<div class="line">        -I #{protoc_dir} \</div>
<div class="line">        #{src}/*.proto</div>
<div class="line">  CMD</div>
<div class="line"> </div>
<div class="line">  # The --objc_out plugin generates a pair of .pbobjc.h/.pbobjc.m files for each .proto file.</div>
<div class="line">  s.subspec &#39;Messages&#39; do |ms|</div>
<div class="line">    ms.source_files = &quot;#{dir}/*.pbobjc.{h,m}&quot;</div>
<div class="line">    ms.header_mappings_dir = dir</div>
<div class="line">    ms.requires_arc = false</div>
<div class="line">    # The generated files depend on the protobuf runtime.</div>
<div class="line">    ms.dependency &#39;Protobuf&#39;</div>
<div class="line">  end</div>
<div class="line"> </div>
<div class="line">  # The --objcgrpc_out plugin generates a pair of .pbrpc.h/.pbrpc.m files for each .proto file with</div>
<div class="line">  # a service defined.</div>
<div class="line">  s.subspec &#39;Services&#39; do |ss|</div>
<div class="line">    ss.source_files = &quot;#{dir}/*.pbrpc.{h,m}&quot;</div>
<div class="line">    ss.header_mappings_dir = dir</div>
<div class="line">    ss.requires_arc = true</div>
<div class="line">    # The generated files depend on the gRPC runtime, and on the files generated by `--objc_out`.</div>
<div class="line">    ss.dependency &#39;gRPC-ProtoRPC&#39;</div>
<div class="line">    ss.dependency &quot;#{s.name}/Messages&quot;</div>
<div class="line">  end</div>
<div class="line"> </div>
<div class="line">  s.pod_target_xcconfig = {</div>
<div class="line">    # This is needed by all pods that depend on Protobuf:</div>
<div class="line">    &#39;GCC_PREPROCESSOR_DEFINITIONS&#39; =&gt; &#39;$(inherited) GPB_USE_PROTOBUF_FRAMEWORK_IMPORTS=1&#39;,</div>
<div class="line">    # This is needed by all pods that depend on gRPC-RxLibrary:</div>
<div class="line">    &#39;CLANG_ALLOW_NON_MODULAR_INCLUDES_IN_FRAMEWORK_MODULES&#39; =&gt; &#39;YES&#39;,</div>
<div class="line">  }</div>
<div class="line">end</div>
</div><!-- fragment --><p>The file should be named <code>&lt;Podspec file name&gt;.podspec</code>.</p>
<p>Note: If your proto files are in a directory hierarchy, you might want to adjust the <em>globs</em> used in the sample Podspec above. For example, you could use:</p>
<p>```ruby s.prepare_command = &lt;&lt;-CMD ... <code>find . -name *.proto -print | xargs</code> CMD ... ms.source_files = "#{dir}/*.pbobjc.{h,m}", "#{dir}/**/*.pbobjc.{h,m}" ... ss.source_files = "#{dir}/*.pbrpc.{h,m}", "#{dir}/**/*.pbrpc.{h,m}" </p><div class="fragment"><div class="line">Once your library has a Podspec, Cocoapods can install it into any XCode project. For that, go into</div>
<div class="line">your project&#39;s directory and create a Podfile by running:</div>
<div class="line"> </div>
<div class="line">```sh</div>
<div class="line">pod init</div>
</div><!-- fragment --><p>Next add a line to your Podfile to refer to your library's Podspec. Use <code>:path</code> as described <a href="https://guides.cocoapods.org/using/the-podfile.html#using-the-files-from-a-folder-local-to-the-machine">here</a>:</p>
<div class="fragment"><div class="line">pod &#39;&lt;Podspec file name&gt;&#39;, :path =&gt; &#39;path/to/the/directory/of/your/podspec&#39;</div>
</div><!-- fragment --><p>You can look at this <a href="https://github.com/grpc/grpc/blob/master/examples/objective-c/helloworld/Podfile">example Podfile</a>.</p>
<p>Finally, in your project's directory, run:</p>
<div class="fragment"><div class="line">pod install</div>
</div><!-- fragment --><p><a class="anchor" id="use"></a> </p>
<h2><a class="anchor" id="autotoc_md271"></a>
Use the generated library in your code</h2>
<p>Please check the <a href="https://github.com/grpc/grpc/tree/master/examples/objective-c">example apps</a> for examples of how to use a generated gRPC library.</p>
<p><a class="anchor" id="no-proto"></a> </p>
<h2><a class="anchor" id="autotoc_md272"></a>
Use gRPC without Protobuf</h2>
<p>This <a href="https://github.com/grpc/grpc/tree/master/src/objective-c/tests/GRPCClientTests.m">tests file</a> shows how to use the generic gRPC Objective-C client without generated protobuf files.</p>
<p><a class="anchor" id="alternatives"></a> </p>
<h2><a class="anchor" id="autotoc_md273"></a>
Alternatives to the steps above</h2>
<p><a class="anchor" id="install"></a> </p>
<h3><a class="anchor" id="autotoc_md274"></a>
Install &lt;em&gt;protoc&lt;/em&gt; with the gRPC plugin</h3>
<p>Although it's not recommended (because it can lead to hard-to-solve version conflicts), it is sometimes more convenient to install <em>protoc</em> 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 <a href="http://brew.sh">homebrew</a>.</p>
<p>The run the following command to install <em>protoc</em> and the gRPC <em>protoc</em> plugin: </p><div class="fragment"><div class="line">$ curl -fsSL https://goo.gl/getgrpc | bash -</div>
</div><!-- fragment --><p>This will download and run the <a href="https://raw.githubusercontent.com/grpc/homebrew-grpc/master/scripts/install">gRPC install script</a>.</p>
<p><a class="anchor" id="no-homebrew"></a> </p>
<h3><a class="anchor" id="autotoc_md275"></a>
Install &lt;em&gt;protoc&lt;/em&gt; and the gRPC plugin without using Homebrew</h3>
<p>First install v3 of the Protocol Buffers compiler (<em>protoc</em>), by cloning <a href="https://github.com/google/protobuf">its Git repository</a> and following these <a href="https://github.com/google/protobuf#c-installation---unix">installation instructions</a> (the ones titled C++; don't miss the note for Mac users).</p>
<p>Then clone this repository and execute the following commands from the root directory where it was cloned.</p>
<p>Compile the gRPC plugins for <em>protoc</em>: </p><div class="fragment"><div class="line">make grpc_objective_c_plugin</div>
</div><!-- fragment --><p>Create a symbolic link to the compiled plugin binary somewhere in your <code>$PATH</code>: </p><div class="fragment"><div class="line">ln -s `pwd`/bins/opt/grpc_objective_c_plugin /usr/local/bin/protoc-gen-objcgrpc</div>
</div><!-- fragment --><p>(Notice that the name of the created link must begin with "`protoc-gen-`" for <em>protoc</em> to recognize it as a plugin).</p>
<p>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 <em>protoc</em>, in which case no system modification nor renaming is necessary.</p>
<p><a class="anchor" id="no-cocoapods"></a> </p>
<h3><a class="anchor" id="autotoc_md276"></a>
Integrate the generated gRPC library without using Cocoapods</h3>
<p>You need to compile the generated <code>.pbobjc.*</code> files (the enums and messages) without ARC support, and the generated <code>.pbrpc.*</code> files (the services) with ARC support. The generated code depends on v0.12+ of the Objective-C gRPC runtime library and v3.0.0-alpha-4+ of the Objective-C Protobuf runtime library.</p>
<p>These libraries need to be integrated into your project as described in their respective Podspec files:</p>
<ul>
<li><a href="https://github.com/grpc/grpc/blob/master/gRPC.podspec">Podspec</a> for the Objective-C gRPC runtime library. This can be tedious to configure manually.</li>
<li><a href="https://github.com/google/protobuf/blob/master/Protobuf.podspec">Podspec</a> for the Objective-C Protobuf runtime library.</li>
</ul>
<h2><a class="anchor" id="autotoc_md277"></a>
Use gRPC with OpenSSL</h2>
<p>gRPC uses BoringSSL as its dependency, which is a fork of OpenSSL and export a number of symbols that are the same as OpenSSL. gRPC avoids conflicts of these symbols by renaming BoringSSL symbols.</p>
<p>If you need gRPC to use OpenSSL instead of BoringSSL (e.g. for the benefit of reducing the binary size of your product), you need to make a local <code>gRPC-Core</code> podspec and tweak it accordingly:</p><ul>
<li>Copy the version of <code>/gRPC-Core.podspec</code> you wish to use from Github into the repository of your app;</li>
<li>In your <code>Podfile</code>, add the following line: <div class="fragment"><div class="line">pod `gRPC-Core`, :podspec =&gt; &quot;.&quot; # assuming gRPC-Core.podspec is in the same directory as your Podfile</div>
</div><!-- fragment --></li>
<li>Remove <a href="https://github.com/grpc/grpc/blob/b24b212ee585d376c618235905757b2445ac6461/gRPC-Core.podspec#L186">the macro</a> <code>GRPC_SHADOW_BORINGSSL_SYMBOLS</code> to disable symbol renaming;</li>
<li>Substitude the <code>BoringSSL-GRPC</code> <a href="https://github.com/grpc/grpc/blob/b24b212ee585d376c618235905757b2445ac6461/gRPC-Core.podspec#L184">dependency</a> to whatever pod of OpenSSL your other libraries use.</li>
</ul>
<p>These steps should allow gRPC to use OpenSSL and drop BoringSSL dependency. If you see any issue, file an issue to us.</p>
<h2><a class="anchor" id="autotoc_md278"></a>
Upgrade issue with BoringSSL</h2>
<p>If you were using an old version of gRPC (&lt;= v1.14) which depended on pod <code>BoringSSL</code> rather than <code>BoringSSL-GRPC</code> and meet issue with the library like: </p><div class="fragment"><div class="line">ld: framework not found openssl</div>
</div><!-- fragment --><p>updating <code>-framework openssl</code> in Other Linker Flags to <code>-framework openssl_grpc</code> in your project may resolve this issue (see <a href="https://github.com/grpc/grpc/issues/16821">#16821</a>). </p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Wed Mar 3 2021 19:20:10 for GRPC Objective-C by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.17
</small></address>
</body>
</html>