apple / swift-protobuf

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 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. Features of SwiftProtobuf SwiftProtobuf offers many advantages over alternative serialization systems: • Safety: The protobuf code-generation system avoids the errors that are common with hand-built serialization code. • Correctness: SwiftProtobuf passes both its own extensive test suite and Google's full conformance test for protobuf correctness. • Schema-driven: Defining your data structures in a separate schema file clearly documents your communications conventions. • Idiomatic: SwiftProtobuf takes full advantage of the Swift language. In particular, all generated types provide full Swift copy-on-write value semantics. • Efficient binary serialization: The method returns a bag of bytes with a compact binary form of your data. You can deserialize the data using the initializer. • Standard JSON serialization: The method returns a JSON form of your data that can be parsed with the initializer. • Hashable, Equatable: The generated struct can be put into a or . • Performant: The binary and JSON serializers have been extensively optimized. • Extensible: You can add your own Swift extensions to any of the generated types. Best of all, you can take the same 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: • Google's protobuf documentation provides general information about protocol buffers, the protoc compiler, and how to use protocol buffers with C++, Java, and other languages. • PLUGIN.md documents the plugin that adds Swift support to the program • API.md documents how to use the generated code. This is recommended reading for anyone using SwiftProtobuf in their project. • INTERNALS.md documents the internal structure of the generated code and the library. This should only be needed by folks interested in working on SwiftProtobuf itself. • STYLE_GUIDELINES.md documents the style guidelines we have adopted in our codebase if you are interested in contributing Getting Started If you've worked with Protocol Buffers before, adding Swift support is very simple: you just need to build the program and copy it into your PATH. The 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: • A Swift 6.0 or later compiler (or, if building with Xcode, Xcode 16.0 or later as required by the App Store). The Swift protobuf project is being developed and tested against the latest release version of Swift available from Swift.org • Google's protoc compiler. The Swift protoc plugin is being actively developed and tested against the latest protobuf sources. The SwiftProtobuf tests need a version of protoc which supports the option (introduced in protoc 3.2.0). It may work with earlier versions of protoc. You can get recent versions from Google's github repository. Building and Installing the Code Generator Plugin To translate 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: Pick what released version of SwiftProtobuf you are going to use. You can get a list of tags with: Once you pick the version you will use, set your local state to match, and build the protoc plugin: This will create a binary called in the directory. To install, just copy this one executable into a directory that is part of your 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 with . Alternatively install via Homebrew If you prefer using Homebrew: This will install compiler and Swift code generator plugin. Converting .proto files into Swift To generate Swift output for your .proto files, you run the command as usual, using the option: The program will automatically look for in your and use it. Each input file will get translated to a corresponding file in the output directory. More information about building and using 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 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 you used to generate the code. ...using After copying the 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 file and import the library into the desired targets. Adjust the here to match the you used to build the plugin above: ...using Xcode If you are using Xcode, then you should: • Add the source files generated from your protos directly to your project • Add this SwiftPM package as dependency of your xcode…