This repository contains an experimental Swift gRPC API and code generator.
It is intended for use with Apple's
swift-protobuf
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.
The Echo example provides a comprehensive demonstration of currently-supported features.
Swift Package Manager builds may also be made on Linux systems. Please see DOCKER.md and LINUX.md for details.
Swift gRPC includes vendored copies of the gRPC core library and BoringSSL, an OpenSSL fork that is used by the gRPC Core. These are built automatically in Swift Package Manager builds.
The recommended way to use Swift gRPC is to first define an API using the Protocol Buffer language and then use the Protocol Buffer Compiler and the Swift Protobuf and gRPC-Swift plugins to generate the necessary support code.
Binary releases of protoc, the Protocol Buffer Compiler, are
available on GitHub.
To build the plugins, run make in the Plugins 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-swiftgrpc, which generates gRPC interface code.
To use the plugins, protoc and both plugins should be in your
search path. Invoke them with commands like the following:
protoc <your proto files> \
--swift_out=. \
--swiftgrpc_out=.
By convention the --swift_out option invokes the protoc-gen-swift
plugin and --swiftgrpc_out invokes protoc-gen-swiftgrpc.
Most grpc-swift development is done with the Swift Package Manager.
For usage in Xcode projects, we rely on the swift package generate-xcodeproj
command to generate an Xcode project for the grpc-swift core libraries.
The top-level Makefile uses the Swift Package Manager to generate an Xcode project for the SwiftGRPC package:
$ make
This will create SwiftGRPC.xcodeproj, which you should
add to your project, along with setting build dependencies
on BoringSSL, CgRPC, and gRPC. Due to present
limitations in Package Manager configuration, the libz
dependency is not included in the generated Xcode project. If
you get build errors about missing symbols such as
_deflate, _deflateEnd, etc., you can fix them by adding
libz.tbd to the Link Binary With Libraries build step
of the CgRPC target.
Please also note that your project will need to include the
SwiftProtobuf.xcodeproj from
Swift Protobuf and
the source files that you generated with protoc and the plugins.
Please see Echo for a working Xcode-based example and file issues if you find any problems.
While the recommended way to use gRPC is with Protocol Buffers and generated code, at its core gRPC is a powerful HTTP/2-based communication system that can support arbitrary payloads. As such, each gRPC library includes low-level interfaces that can be used to directly build API clients and servers with no generated code. For an example of this in Swift, please see the Simple example.
grpc-swift depends on Swift, Xcode, and swift-proto. We are currently testing with the following versions:
- Xcode 9
- Swift 4 (swiftlang-900.0.43 clang-900.0.22.8)
- swift-protobuf 0.9.904
grpc-swift is released under the same license as gRPC, repeated in LICENSE.
Please get involved! See our guidelines for contributing.