gRPC Swift
This repository contains a gRPC Swift API and code generator.
It is intended for use with Apple's SwiftProtobuf support for
Protocol Buffers. Both projects contain code generation plugins for protoc
,
Google's Protocol Buffer compiler, and both contain libraries of supporting code
that is needed to build and run the generated code.
APIs and generated code is provided for both gRPC clients and servers, and can be built either with Xcode or the Swift Package Manager. Support is provided for all four gRPC API styles (Unary, Server Streaming, Client Streaming, and Bidirectional Streaming) and connections can be made either over secure (TLS) or insecure channels.
Versions
gRPC Swift has recently been rewritten on top of SwiftNIO as opposed to the core library provided by the gRPC project.
Version | Implementation | Branch | protoc Plugin |
CocoaPod | Support |
---|---|---|---|---|---|
1.x | SwiftNIO | main |
protoc-gen-grpc-swift |
gRPC-Swift | Actively developed and supported |
0.x | gRPC C library | cgrpc |
protoc-gen-swiftgrpc |
SwiftGRPC | No longer developed; security fixes only |
The remainder of this README refers to the 1.x version of gRPC Swift.
Supported Platforms
gRPC Swift's platform support is identical to the platform support of Swift NIO.
The earliest supported Swift version for gRPC Swift 1.8.x and newer is 5.4. For 1.7.x and earlier the oldest supported Swift version is 5.2.
Versions of clients and services which are use Swift's Concurrency support are available from gRPC Swift 1.8.0 and require Swift 5.6 and newer.
Getting gRPC Swift
There are two parts to gRPC Swift: the gRPC library and an API code generator.
Getting the gRPC library
Swift Package Manager
The Swift Package Manager is the preferred way to get gRPC Swift. Simply add the
package dependency to your Package.swift
:
dependencies: [
.package(url: "https://github.com/grpc/grpc-swift.git", from: "1.0.0")
]
...and depend on "GRPC"
in the necessary targets:
.target(
name: ...,
dependencies: [.product(name: "GRPC", package: "grpc-swift")]
]
Xcode
From Xcode 11 it is possible to add Swift Package dependencies to Xcode
projects and link targets to products of those packages; this is the
easiest way to integrate gRPC Swift with an existing xcodeproj
.
Manual Integration
Alternatively, gRPC Swift can be manually integrated into a project:
- Build an Xcode project:
swift package generate-xcodeproj
, - Add the generated project to your own project, and
- Add a build dependency on
GRPC
.
CocoaPods
gRPC Swift is currently available from CocoaPods. To integrate, add
the following line to your Podfile
:
pod 'gRPC-Swift', '~> 1.0.0'
Then, run pod install
from command line and use your project's generated
.xcworkspace
file. You might also need to add use_frameworks!
to your Podfile
.
protoc
Plugins
Getting the Binary releases of protoc
, the Protocol Buffer Compiler, are available on
GitHub.
To build the plugins, run make plugins
in the main directory. This uses the
Swift Package Manager to build both of the necessary plugins:
protoc-gen-swift
, which generates Protocol Buffer support code and
protoc-gen-grpc-swift
, which generates gRPC interface code.
To install these plugins, just copy the two executables (protoc-gen-swift
and
protoc-gen-grpc-swift
) that show up in the main directory into a directory
that is part of your PATH
environment variable. Alternatively the full path to
the plugins can be specified when using protoc
.
Alternatively, you can get the latest precompiled version of the plugins by adding
the following line to your Podfile
:
pod 'gRPC-Swift-Plugins'
The plugins are available in the Pods/gRPC-Swift-Plugins/
folder afterwards.
Homebrew
The plugins are available from homebrew and can be installed with:
$ brew install swift-protobuf grpc-swift
Examples
gRPC Swift has a number of tutorials and examples available. They are split across two directories:
/Sources/Examples
contains examples which do not require additional dependencies and may be built using the Swift Package Manager./Examples
contains examples which rely on external dependencies or may not be built by the Swift Package Manager (such as an iOS app).
Some of the examples are accompanied by tutorials, including:
- A quick start guide for creating and running your first gRPC service.
- A basic tutorial covering the creation and implementation of a gRPC service using all four call types as well as the code required to setup and run a server and make calls to it using a generated client.
- An interceptors tutorial covering how to create and use interceptors with gRPC Swift.
Documentation
The docs
directory contains documentation, including:
- Options for the
protoc
plugin indocs/plugin.md
- How to configure TLS in
docs/tls.md
- How to configure keepalive in
docs/keepalive.md
- Support for Apple Platforms and NIO Transport Services in
docs/apple-platforms.md
Security
Please see SECURITY.md.
License
gRPC Swift is released under the same license as gRPC, repeated in LICENSE.
Contributing
Please get involved! See our guidelines for contributing.