The Swift language implementation of gRPC.
Clone or download
Latest commit 1d422fc Nov 16, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/ISSUE_TEMPLATE Docs/add question template (#310) Sep 12, 2018
Assets Update CgRPC to v1.12.0 and BoringSSL to 10.0.4 (I guess?). This chan… May 29, 2018
Docker Update Dockerfile Jul 14, 2018
Examples Update README.md Sep 5, 2018
Sources Add support for RPC status (#331) Nov 9, 2018
SwiftGRPC-Carthage.xcodeproj Minor tweaks in preparation for SwiftGRPCNIO. Oct 16, 2018
Tests Add support for RPC status (#331) Nov 9, 2018
scripts Remove comment Jun 12, 2018
.gitignore Fix building with a clean Xcode and add a CI run to ensure just that. Jun 4, 2018
.gitmodules Move CgRPC, gRPC, and QuickProto to "Sources" directory and add new t… Dec 27, 2016
.travis-install.sh Minor tweaks in preparation for SwiftGRPCNIO. Oct 16, 2018
.travis.yml Remove build-carthage altogether from CI for now. Oct 16, 2018
AUTHORS Relicense to Apache 2, change owners to "the gRPC Authors". Jun 2, 2017
CONTRIBUTING.md Update CLA link to point to CNCF CLA. Aug 24, 2018
DOCKER.md update PROTOBUF Feb 18, 2018
LICENSE Relicense to Apache 2, change owners to "the gRPC Authors". Jun 2, 2017
LINUX.md Remove Linux RUNME.sh script Aug 21, 2018
Makefile Merge pull request #323 from grpc/plugin-and-docs Oct 22, 2018
OVERVIEW.md Fix font weight formatting in OVERVIEW.md Apr 25, 2017
PATENTS Add PATENTS declaration Sep 23, 2016
Package.swift Update SwiftProtobuf to 1.1.1 Aug 21, 2018
README.md Merge pull request #323 from grpc/plugin-and-docs Oct 22, 2018
SwiftGRPC.podspec Cut a 0.6.0 release due to the breaking changes in SwiftProtobuf 1.1 Sep 3, 2018
fix-project-settings.rb Add io.grpc. prefix to bundle identifier Sep 11, 2018
patch-carthage-project.rb Project patch script rework. Aug 16, 2018
swift-vendoring.sh.template Updating for grpc-1.4.5, WIP. Builds but does not pass tests. Aug 21, 2017
vendor-boringssl.sh Update CgRPC to v1.12.0 and BoringSSL to 10.0.4 (I guess?). This chan… May 29, 2018
vendor-grpc.sh Move another compiler directive into vendor-grpc.sh. Jun 4, 2018

README.md

Build Status

Swift gRPC

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.

CocoaPods integration

Swift gRPC is currently available from CocoaPods. To integrate, add the following line to your Podfile:

pod 'SwiftGRPC'

Then, run pod install from command line and use your project's generated .xcworkspace file.

Manual integration

When not using CocoaPods, 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.

After building your project, add the generated SwiftGRPC.xcodeproj to your project, and add build dependencies on BoringSSL, CgRPC, and SwiftGRPC.

Please also note that your project will need to include the SwiftProtobuf.xcodeproj from Swift Protobuf and the source files that you generate with protoc/plugins.

See Echo for a working Xcode-based example, and don't hesitate to file issues if you find any problems.

Usage

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 Swift gRPC plugins to generate the necessary support code.

Getting the plugins

Binary releases of protoc, the Protocol Buffer Compiler, are available on GitHub.

To build the plugins, run make plugin 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-swiftgrpc, which generates gRPC interface code.

To install these plugins, just copy the two executables (protoc-gen-swift and protoc-gen-swiftgrpc) that show up in the main directory into a directory that is part of your PATH environment variable.

Using the plugins

To use the plugins, protoc and both plugins should be in your search path (see above). 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.

Parameters

To pass extra parameters to the plugin, use a comma-separated parameter list separated from the output directory by a colon.

Flag Values Default Description
Visibility Internal/Public Internal ACL of generated code
Server true/false true Whether to generate server code
Client true/false true Whether to generate client code
Async true/false true Whether to generate asynchronous code
Sync true/false true Whether to generate synchronous code
TestStubs true/false false Whether to generate test stub code

Example:

$ protoc <your proto> --swiftgrpc_out=Client=true,Server=false:.

Building your project

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 && make project

This will create SwiftGRPC.xcodeproj, which you should add to your project, along with setting the necessary build dependencies mentioned above.

Low-level gRPC

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.

Having build problems?

grpc-swift depends on Swift, Xcode, and swift-protobuf. We are currently testing with the following versions:

  • Xcode 9.1
  • Swift 4.0
  • swift-protobuf 1.1.1

License

grpc-swift is released under the same license as gRPC, repeated in LICENSE.

Contributing

Please get involved! See our guidelines for contributing.

Releasing

Prior to creating a new release tag for SwiftGRPC, the .podspec file's version should be bumped, and the CocoaPods spec linter should be run to ensure that there are no new warnings/errors:

$ pod spec lint SwiftGRPC.podspec

Once a new release tag is created, the updated CocoaPods spec should also be pushed to the master specs repo:

$ pod trunk push SwiftGRPC.podspec