swift-protobuf

Swift Protobuf

Welcome to Swift Protobuf, a powerful tool that bridges Apple's Swift programming language with Google's Protocol Buffer (protobuf) serialization technology, both known for their high performance and programmer safety. This project provides solutions to generate Swift code from proto files and includes a crucial runtime library for utilizing the generated Swift code effectively.

Features of SwiftProtobuf

SwiftProtobuf stands out with numerous advantages in serialization:

• Safety: Eliminates common errors associated with manual serialization.
• Correctness: Passes extensive test suites, including Google’s standards for protobuf accuracy.
• Schema-driven: Utilizing .proto schema files documents your data communication structures clearly.
• Idiomatic: Fully utilizes Swift's features, including copy-on-write value semantics in generated types.
• Efficient Binary Serialization: Offers compact data serialization and straightforward deserialization.
• Standard JSON Serialization: Provides JSON serialization with simple parsing capabilities.
• Hashable and Equatable: Supports data structures to be used in sets and dictionaries.
• Performance: Highly optimized for both binary and JSON serialization.
• Extensibility: Allows enhancements through Swift extensions in generated types.

Moreover, a single .proto file can generate code for Java, C++, Python, or Objective-C, facilitating effortless data exchange across platforms with consistent serialization practices.

Documentation

Swift Protobuf offers extensive documentation to aid users:

• General Overview: Find Google's protobuf documentation for a broader understanding of protocol buffers.
• Plugin Documentation: Learn about the protoc-gen-swift plugin that enhances Swift compatibility.
• API Usage: A guide for using the generated code within projects.
• Internal Structure: For those interested in Swift Protobuf’s inner workings.
• Style Guidelines: Important for contributors to maintain coding standards.

Getting Started

Swift Protobuf is straightforward to integrate, especially if you are familiar with Protocol Buffers. Here's how to get started:

System Requirements

You'll need:

• Swift 5.8 or later (Xcode 14.3+ for App Store requirements).
• Google's protoc compiler, preferably the latest version for optimal compatibility.

Building and Installing

Firstly, download the Swift Protobuf repository:

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

Select a version from the available tags and build the plugin:

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

This compiles the protoc-gen-swift binary which you should place in your PATH.

Installation Alternatives

Alternatively, through Homebrew:

brew install swift-protobuf

This fetches both the protoc compiler and the Swift plugin.

Converting .proto Files

Generate Swift code using the protoc command:

protoc --swift_out=. my.proto

Each .proto file will be transformed into a .pb.swift file for use.

Adding the Library to Your Project

Use one of these methods to integrate the SwiftProtobuf library:

• Swift Package Manager: Add a dependency to Package.swift.
• Xcode: Include the .pb.swift files and the SwiftProtobuf package.
• CocoaPods: Add pod 'SwiftProtobuf', '~> 1.0' to your Podfile.

Quick Start

After setting up, use the generated Swift structs like any other Swift code. Here's an example to serialize and deserialize a proto message:

var info = BookInfo()
info.id = 1734
info.title = "Really Interesting Book"
info.author = "Jane Smith"

// Serialize
let binaryData: Data = try info.serializedBytes()
let jsonData: Data = try info.jsonUTF8Data()

// Deserialize
let decodedInfo = try BookInfo(serializedData: binaryData)
let receivedFromJSON = try BookInfo(jsonUTF8Bytes: jsonData)

For detailed API usage, consult the API Documentation.

Report any issues

In case of issues, provide detailed reports including OS version, Swift version, protoc version, and any specific modifications. This information will assist in swift troubleshooting.

SwiftProtobuf truly empowers developers to harness the full potential of Swift and Protocol Buffers together, facilitating a smooth transition from protocol definitions to efficient, Swift-native code structures.