Swiftpack.co - Package - 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 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:

  • 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 .proto 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 .serializedData() method returns a Data with a compact binary form of your data. You can deserialize the data using the init(serializedData:) initializer.
  • Standard JSON serialization: The .jsonUTF8Data() method returns a JSON form of your data that can be parsed with the init(jsonUTF8Data:) initializer.
  • Hashable, Equatable: The generated struct can be put into a Set<> or Dictionary<>.
  • 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 .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:

  • 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 protoc-gen-swift plugin that adds Swift support to the protoc program
  • API.md documents how to use the generated code. This is recommended reading for anyone using SwiftProtobuf in their project.
  • cocoadocs.org has the generated API documentation
  • 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 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:

  • A Swift 4.2 or later compiler (Xcode 10.0 or later). Support is included for the Swift Package Manager; or using the included Xcode project. 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 swift_prefix 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 .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.6.0" here to match the [tag_name] you used to build the plugin above:

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

...using Xcode

If you are using Xcode, then you should:

  • Add the .pb.swift source files generated from your protos directly to your project
  • Add the appropriate SwiftProtobuf_<platform> target from the Xcode project in this package to your project.

...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.

...using Carthage

If you're using Carthage, add this to your Cartfile but adjust the tag to match the [tag_name] you used to build the plugin above:

github "apple/swift-protobuf" ~> 1.0

Run carthage update and drag SwiftProtobuf.framework into your Xcode.project.

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:
let binaryData: Data = try info.serializedData()

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

// Serialize to JSON format as a Data object
let jsonData: Data = try info.jsonUTF8Data()

// Deserialize from JSON format from `jsonData`
let receivedFromJSON = try BookInfo(jsonUTF8Data: jsonData)

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:

  • The specific operating system and version (for example, "macOS 10.12.1" or "Ubuntu 16.10")
  • The version of Swift you have installed (from swift --version)
  • The version of the protoc compiler you are working with from protoc --version
  • The specific version of this source code (you can use git log -1 to get the latest commit ID)
  • Any local changes you may have

Github

link
Stars: 3306

Dependencies

Used By

Total: 0

Releases

1.14.0 Release -

Notable Changes:

  • Don't allow raw LF or CR in the middle of TextFormat string literals. #1085 – TextFormat was used as input (tests, etc.), then previously working multiline strings might no longer parse. This is to bring the library in alignment with the protocolbuffers conformance tests.

Minor Changes:

  • Fix issue with oneof being named newValue #1087
  • Support unicode escapes in TextFormat #1085

1.13.0 Release -

Notable Changes:

  • Sort map fields for TextFormat (to match spec) #1076 Minor Changes:
  • Reduce foundation usage #1064
  • The CocoaPod spec and checked in Xcode project were updated to move the minimum iOS version to 9.0 to avoid warnings in Xcode 12 #1082

1.12.0 Release -

Notable Changes:

  • Change code generation to reduce the stack usage in non optimized builds (Issue #1034)
    • Move required field support for oneof into a generated helper (#1041)
    • Work around stack usage for non optimize build and switch statements (#1040)
    • Work around excessive stack space in non optimized builds during oneof isInitialized (#1042)
  • Revise the way storage calculations are done to take into account the cost of singular message fields since those directly increase the size of the containing message (#1046)
  • Fix JSON coding/decoding of NullValue WKT (#1051)

Minor Changes:

  • Minor oneof tweak: don't generate case nil when also generating a default (#1035)
  • Factor out the common decodeJSON from all the wrappers (#1062)

1.11.0 Release -

Minor changes:

  • Remove empty Data singleton (#1028)
  • Factor SwiftProtobuf module name into the namer, add SwiftProtobufModuleName (#1017)
  • Eliminate NamingUtils's awareness of SwiftProtobufNamer (#1030)

1.10.2 Release -

Minor fix for an accidental api break in the 1.10.0 Release.

  • Fixes and version bump to right api break (#1027)

1.10.1 Release -

Minor fix for an accidental api break in the 1.10.0 Release.

  • Add back the old init signatures. (#1023)

1.10.0 Release -

Notable Changes:

  • Support Proto2 extensions in JSON coder/decoder (#1002)

Minor Changes:

  • Add visitRepeated* methods to the BinaryEncodingSizeVisitory. (#1009)
  • Fix for newer Xcode/swift versions: var --> let to eliminate warning (#975)
  • Don't use StaticString.utf8Start unless there is a pointer rep. (#1015)

1.9.0 Release -

  • Better handing of proto identifiers that start with underscores and numbers #947 #954
  • Added CMake based build for platforms with SwiftPM #957
  • Use withContiguousStorageIfAvailable for String encoding in BinaryEncoder #949
  • Make setting a repeated extension field to [] clear it #966
  • Declare the MessageExtensions with the correct visibility. #969
  • Support for new Proto3 optional (this needs a protoc from protocolbuffers/protobuf v3.12.0 (or later)) #978
  • Provide some more map helpers in the plugin library like the C++ Descriptor. #983
  • Move the SwiftProtobuf.xcodeproj build settings into xcconfig files #986

1.8.0 Release -

New features/interfaces:

  • Add Message binary decoding support from ContiguousBytes (#914)
  • Make things generic over ContiguousBytes and @inlinable (#915, #921)

Notable changes:

  • Use heap-based storage only when a Protobuf has a singular transitive recursion (#900)
  • Use raw pointers instead of typed pointers (#918)
  • Add missing CaseIterable support for nested enums (#923)
  • Guard against TextFormat encoding of unknowns from overflowing the stack (#927)

Performance related changes:

  • JSON/TextFormat submessage encoding performance improvements (#916)
  • Avoid collecting unknown fields while scanning for message (#924)
  • Minor code cleanup for JSON additions (#935)

SwiftProtobuf 1.7.0 Release -

Complete support for Swift 5.1.

Additions to the library:

  • The generated code for descriptor.proto is now included in the library, this means one no longer has to generate and compile it in if there are proto files that had extension declared on those types. (#727)

Notable changes:

  • The Swift 5.1 compiler will error on switch statements for an enum if it has a large number of cases; this could happen in the generated code. The generated code now splits things up to avoid this compile error. (#904)

SwiftProtobuf 1.6.0 Release -

Notable updates:

  • Raise a .illegalNull is the top level JSON is null. (#870)
  • Perf: Use new float formatting code (#882)
  • Specify swift_versions in podspec and minimum CocoaPods 1.7.0 version. (#891)

SwiftProtobuf 1.5.0 Release -

Complete support for Swift 5.

  • Swift5: Fix warnings about loss of precision (#844)
  • Drop the support for Swift <4.0. (#847)
  • Swift5.0: Change Data(bytes:) to Data(_:). (#848)
  • Fix build command to work also with Swift 5. (#852)
  • Swift 5.0: Switch a stray Data(bytes:) to Data(_:). (#854)
  • Swift 5: adopt new Data.withUnsafeBytes API. (#843)

Update some internals:

  • Update some FileIo calls to FileHandle. (#845)
  • Remove printToFd logic from FileIo. (#846)

Add some features to the library:

  • TextFormat conformance: Add option to suppress unknown field printing. (#850)
  • Adding JSON encoding option: Use proto field names instead of lowerCamelCase names. (#856)

SwiftProtobuf 1.4.0 Release -

Minor updates around some edge conditions in TextFormat/JSON format:

  • The empty string is a valid JSON encoding for a FieldMask. (#835)
  • Accept too-large float values in Text format (#840)

SwiftProtobuf 1.3.1 Release -

Minor release to fix building with Swift versions <4.2 (#828).

SwiftProtobuf 1.3.0 Release -

  • SwiftPM Updates to be in better shape for Swift 5. (#819, #824)
  • Code updates for Swift 5 being more strict about some things (#808, #809)
  • Avoid generating code that doesn't compile when enum case aliases have naming collisions in their Swift forms (#822)
  • Drop support for Swift <=3.1 since 4.2 has been the current GM for a while now. (#825)

SwiftProtobuf 1.2.0 Release -

Changes of interest:

  • #800 Add JSON encoding options: Not, this is a source compatible change, but not binary compatible because of a new parameter with a default, hence the 1.2.0 version numbers.
  • #804 Fix Json map encoding for float, sint, fixed, sfixed

SwiftProtobuf 1.1.2 Release -

Release to provide full Swift 4.2 toolchain support. Most interesting Pull Requests:

  • Hashable conformance and Hashing changes #784

The 1.1.0 Release already included #764 (SwiftPM 4.2 specific manifest), #766 (CaseIterable for enums).

SwiftProtobuf 1.1.1 Release -

  • #781 & #783 - avoid extra indirection on equality methods.
  • #785 fixes long standing (and overlooked) issue around clear* methods when the used shared heap storage with another instance.

SwiftProtobuf 1.1.0 Release -

Changes of interest:

  • Support for Swift < 3.1 has been dropped. (#736, #765)
  • Some fixes around text_format parsing (#738)
  • Added missing support for escape sequences in JSON byte data (#744)
  • Start taking advantage of the support from conditional conformances (#747, #749, #755)
  • Fail for unknown JSON fields, but provide an option to ignore them instead (#771)
  • Start Swift 4.2 support (#764, #766). There will be more work for this in future releases.

Note: This release includes a correction to the handing of unknown fields when parsing JSON messages. Previous releases were not matching the Protobuf Spec which calls for unknown fields to error. The spec does allow for an option to request that unknown fields are silently dropped. So this release includes the fix to error for unknown fields, but adds an option to JSONDecodingOptions to request unknown fields be ignored instead of causing the failure. PR #771 includes these changes and more details.

SwiftProtobuf 1.0.3 Release -

Release to provide Swift 4.1 toolchain support. Most interesting Pull Requests:

  • #716 Support for Swift 4.1's SE0187 changes.
  • #718 More Swift 4.1 cleanups
  • #719 Swift 4.1 added warnings for "near misses" with default impls of protocols that cause build warning in generated code

SwiftProtobuf 1.0.2 Release -

Minor release to provide:

  • Updated SwiftPM 4 manifest to expose the plugin library for people writing other plugins (#702)

SwiftProtobuf 1.0.1 Release -

Minor update release to provide:

  • Swift 4.0.x and Xcode 9.1 specific tweaks (new deprecation warnings from the tools, etc.)
  • Added a SwiftPM 4 package file (to support both the older and newer SwiftPM).

SwiftProtobuf 1.0.0 Release -

This first official stable release of SwiftProtobuf is the result of a collaboration between Apple and Google engineers to produce a world-class protobuf implementation for use by Swift developers.

P.S. A heartfelt "Thanks!" to all the folks who helped get us to this point by submitting code, asking questions, and simply using the pre-release versions. We could not have done it without you!

Swift 4 compatibility and general performance -

This includes a number of specific fixes so the code builds cleanly in both Swift 3 and Swift 4. It also includes a variety of performance improvements, especially for the code generator.

-