Home

Awesome

<img src="https://swift.org/assets/images/swift.svg" alt="Swift logo" height="70" >

Swift Protobuf

Welcome to Swift Protobuf!

Apple's Swift programming language is a perfect complement to Google's Protocol Buffer ("protobuf") serialization technology. They both emphasize high performance and programmer safety.

This project provides both the command-line program that adds Swift code generation to Google's protoc and the runtime library that is necessary for using the generated code. After using the protoc plugin to generate Swift code from your .proto files, you will need to add this library to your project.

Build and Test Check Upstream Protos Run Conformance Tests

Features of SwiftProtobuf

SwiftProtobuf offers many advantages over alternative serialization systems:

Best of all, you can take the same .proto file and generate Java, C++, Python, or Objective-C for use on other platforms. The generated code for those languages will use the exact same serialization and deserialization conventions as SwiftProtobuf, making it easy to exchange serialized data in binary or JSON forms, with no additional effort on your part.

Documentation

More information is available in the associated documentation:

Getting Started

If you've worked with Protocol Buffers before, adding Swift support is very simple: you just need to build the protoc-gen-swift program and copy it into your PATH. The protoc program will find and use it automatically, allowing you to build Swift sources for your proto files. You will also, of course, need to add the SwiftProtobuf runtime library to your project as explained below.

System Requirements

To use Swift with Protocol buffers, you'll need:

Building and Installing the Code Generator Plugin

To translate .proto files into Swift, you will need both Google's protoc compiler and the SwiftProtobuf code generator plugin.

Building the plugin should be simple on any supported Swift platform:

git clone https://github.com/apple/swift-protobuf.git
cd swift-protobuf

Pick what released version of SwiftProtobuf you are going to use. You can get a list of tags with:

git tag -l

Once you pick the version you will use, set your local state to match, and build the protoc plugin:

git checkout tags/[tag_name]
swift build -c release

This will create a binary called protoc-gen-swift in the .build/release directory.

To install, just copy this one executable into a directory that is part of your PATH environment variable.

NOTE: The Swift runtime support is now included with macOS. If you are using old Xcode versions or are on older system versions, you might need to use also use --static-swift-stdlib with swift build.

Alternatively install via Homebrew

If you prefer using Homebrew:

brew install swift-protobuf

This will install protoc compiler and Swift code generator plugin.

Converting .proto files into Swift

To generate Swift output for your .proto files, you run the protoc command as usual, using the --swift_out=<directory> option:

protoc --swift_out=. my.proto

The protoc program will automatically look for protoc-gen-swift in your PATH and use it.

Each .proto input file will get translated to a corresponding .pb.swift file in the output directory.

More information about building and using protoc-gen-swift can be found in the detailed Plugin documentation.

Adding the SwiftProtobuf library to your project...

To use the generated code, you need to include the SwiftProtobuf library module in your project. How you do this will vary depending on how you're building your project. Note that in all cases, we strongly recommend that you use the version of the SwiftProtobuf library that corresponds to the version of protoc-gen-swift you used to generate the code.

...using swift build

After copying the .pb.swift files into your project, you will need to add the SwiftProtobuf library to your project to support the generated code. If you are using the Swift Package Manager, add a dependency to your Package.swift file and import the SwiftProtobuf library into the desired targets. Adjust the "1.27.0" here to match the [tag_name] you used to build the plugin above:

dependencies: [
    .package(url: "https://github.com/apple/swift-protobuf.git", from: "1.27.0"),
],
targets: [
    .target(
      name: "MyTarget",
      dependencies: [.product(name: "SwiftProtobuf", package: "swift-protobuf")]
    ),
]

...using Xcode

If you are using Xcode, then you should:

...using CocoaPods

If you're using CocoaPods, add this to your Podfile adjusting the :tag to match the [tag_name] you used to build the plugin above:

pod 'SwiftProtobuf', '~> 1.0'

And run pod install.

NOTE: CocoaPods 1.7 or newer is required.

Quick Start

Once you have installed the code generator, used it to generate Swift code from your .proto file, and added the SwiftProtobuf library to your project, you can just use the generated types as you would any other Swift struct.

For example, you might start with the following very simple proto file:

syntax = "proto3";

message BookInfo {
   int64 id = 1;
   string title = 2;
   string author = 3;
}

Then generate Swift code using:

protoc --swift_out=. DataModel.proto

The generated code will expose a Swift property for each of the proto fields as well as a selection of serialization and deserialization capabilities:

// Create a BookInfo object and populate it:
var info = BookInfo()
info.id = 1734
info.title = "Really Interesting Book"
info.author = "Jane Smith"

// As above, but generating a read-only value:
let info2 = BookInfo.with {
    $0.id = 1735
    $0.title = "Even More Interesting"
    $0.author = "Jane Q. Smith"
  }

// Serialize to binary protobuf format: you can choose to serialize into
// any type conforming to `SwiftProtobufContiguousBytes`. For example:
// Resolve the `SwiftProtobufContiguousBytes` return value to `Data`
let binaryData: Data = try info.serializedBytes()
// Resolve the `SwiftProtobufContiguousBytes` return value to `[UInt8]`
let binaryDataAsBytes: [UInt8] = try info.serializedBytes()

// Note that while the `serializedBytes()` spelling is generally preferred,
// you may also use `serializedData()` to get the bytes as an instance of 
// `Data` where required.
// This means that the following two statements are equivalent:
// let binaryData: Data = try info.serializedBytes()
// let binaryData: Data = try info.serializedData()

// Deserialize a received Data object from `binaryData`
let decodedInfo = try BookInfo(serializedData: binaryData)

// Deserialize a received [UInt8] object from `binaryDataAsBytes`
let decodedInfo = try BookInfo(serializedBytes: binaryDataAsBytes)

// Serialize to JSON format as a Data object, or as any other type conforming to
// SwiftProtobufContiguousBytes. For example:
let jsonData: Data = try info.jsonUTF8Data()
let jsonBytes: [UInt8] = try info.jsonUTF8Bytes()

// Deserialize from JSON format from `jsonBytes`
let receivedFromJSON = try BookInfo(jsonUTF8Bytes: jsonBytes)

You can find more information in the detailed API Documentation.

Report any issues

If you run into problems, please send us a detailed report. At a minimum, please include: