thomasvl [ObjC] Properly annotate extensions for ARC.
Just like fields, some extension fieldnames can be named such that they appear
to have meaning to ARC. Add the annotation to the compiler will get things
correct.

Add a bunch of extensions to allow inspection on generation to ensure things
are correct.
Latest commit 1484b58 Dec 5, 2018
Permalink
Type Name Latest commit message Commit time
..
Failed to load latest commit information.
DevTools Make sure Objective C Proto compiler doesn't "duplicate" prefixes unn… Nov 27, 2018
ProtocolBuffers_OSX.xcodeproj Make sure Objective C Proto compiler doesn't "duplicate" prefixes unn… Nov 27, 2018
ProtocolBuffers_iOS.xcodeproj Make sure Objective C Proto compiler doesn't "duplicate" prefixes unn… Nov 27, 2018
Tests [ObjC] Properly annotate extensions for ARC. Dec 5, 2018
google/protobuf Updated checked-in generated code Nov 9, 2018
.gitignore Expand the OS X/Xcode gitignores May 19, 2016
GPBArray.h Annotate the GPBArray enumerate* apis with NS_NOESCAPE. Dec 5, 2018
GPBArray.m Annotate the GPBArray enumerate* apis with NS_NOESCAPE. Dec 5, 2018
GPBArray_PackagePrivate.h Alpha 1 drop of Google's Objective C plugin and runtime support for p… May 6, 2015
GPBBootstrap.h [protos/objc] Include more context in deprecation messages ⚠️ Dec 3, 2018
GPBCodedInputStream.h Adds pushLimit: and popLimit: into GPBCodedInputStream (#2297) Oct 27, 2016
GPBCodedInputStream.m Replace repo links. Aug 22, 2018
GPBCodedInputStream_PackagePrivate.h Migrate away from deprecated OSAtomic APIs. (#4184) Jan 22, 2018
GPBCodedOutputStream.h ObjC: Document the exceptions on some of the writing apis. Jun 19, 2017
GPBCodedOutputStream.m Check return value on write of raw pointer Mar 8, 2018
GPBCodedOutputStream_PackagePrivate.h HeaderDoc support in the library and generated sources Mar 7, 2016
GPBDescriptor.h [ObjC] Add ability to introspect list of enum values (#4678) May 29, 2018
GPBDescriptor.m Added safety checks when malloc returns nil in GPBDescriptor Nov 4, 2018
GPBDescriptor_PackagePrivate.h ObjC: Preserve unknown fields in proto3 syntax files. Jun 6, 2017
GPBDictionary.h Annotate the GPBDictionary enumerate* apis with NS_NOESCAPE. Dec 5, 2018
GPBDictionary.m Annotate the GPBDictionary enumerate* apis with NS_NOESCAPE. Dec 5, 2018
GPBDictionary_PackagePrivate.h Beta quality drop of Objective C Support. Jun 8, 2015
GPBExtensionInternals.h Beta quality drop of Objective C Support. Jun 8, 2015
GPBExtensionInternals.m Add more warnings to for the ObjC runtime build May 25, 2016
GPBExtensionRegistry.h Fixes extra whitespace on generated comments. (#1950) Aug 12, 2016
GPBExtensionRegistry.m Fix ExtensionRegistry copying and add tests. May 17, 2017
GPBMessage.h ObjC: Document the exceptions on some of the writing apis. Jun 19, 2017
GPBMessage.m ObjC: small improvement to extension serialization. Nov 19, 2018
GPBMessage_PackagePrivate.h Work around strange error with atomic and swift under Xcode 8.3.3. Jan 31, 2018
GPBProtocolBuffers.h Better support for using the proto library from a framework. May 24, 2016
GPBProtocolBuffers.m Don't #import the .m files. Jul 7, 2016
GPBProtocolBuffers_RuntimeSupport.h Trim imports for bundled generated protos. Apr 2, 2018
GPBRootObject.h Migrating documentation of the ObjectiveC runtime code to appledoc. (#… Aug 8, 2016
GPBRootObject.m Remove unreferenced 'GPBMessageSignatureProtocol' class. Nov 14, 2017
GPBRootObject_PackagePrivate.h Beta quality drop of Objective C Support. Jun 8, 2015
GPBRuntimeTypes.h Migrating documentation of the ObjectiveC runtime code to appledoc. (#… Aug 8, 2016
GPBUnknownField.h Expose the initializer for unknown fields. Jul 5, 2017
GPBUnknownField.m Add header need for module maps. Aug 6, 2018
GPBUnknownFieldSet.h Migrating documentation of the ObjectiveC runtime code to appledoc. (#… Aug 8, 2016
GPBUnknownFieldSet.m Remove the custom key functions and just use the system provided defa… Sep 19, 2016
GPBUnknownFieldSet_PackagePrivate.h Alpha 1 drop of Google's Objective C plugin and runtime support for p… May 6, 2015
GPBUnknownField_PackagePrivate.h Expose the initializer for unknown fields. Jul 5, 2017
GPBUtilities.h Add GPBMessageDropUnknownFieldsRecursively() and tests. Feb 23, 2017
GPBUtilities.m TextFormat extension printing fix. Nov 14, 2018
GPBUtilities_PackagePrivate.h Add casts to removed undefined behaviors around shifts. Jan 31, 2018
GPBWellKnownTypes.h Timestamp helper fix, Duration helper cleanup. Jan 13, 2017
GPBWellKnownTypes.m Timestamp helper fix, Duration helper cleanup. Jan 13, 2017
GPBWireFormat.h Validate the tag numbers when parsing. (#1725) Jun 29, 2016
GPBWireFormat.m Validate the tag numbers when parsing. (#1725) Jun 29, 2016
README.md Remove/replace travis references (#4953) Jul 23, 2018
generate_well_known_types.sh Fix cp -r usage to be portable. Apr 29, 2016

README.md

Protocol Buffers - Google's data interchange format

Build status Build status Build status Build status

Copyright 2008 Google Inc.

This directory contains the Objective C Protocol Buffers runtime library.

Requirements

The Objective C implementation requires:

  • Objective C 2.0 Runtime (32bit & 64bit iOS, 64bit OS X).
  • Xcode 8.0 (or later).
  • The library code does not use ARC (for performance reasons), but it all can be called from ARC code.

Installation

The distribution pulled from github includes the sources for both the compiler (protoc) and the runtime (this directory). After cloning the distribution and needed submodules (see the src directory's README), to build the compiler and run the runtime tests, you can use:

 $ objectivec/DevTools/full_mac_build.sh

This will generate the src/protoc binary.

Building

There are two ways to include the Runtime sources in your project:

Add objectivec/*.h, objectivec/google/protobuf/*.pbobjc.h, and objectivec/GPBProtocolBuffers.m to your project.

or

Add objectivec/*.h, objectivec/google/protobuf/*.pbobjc.h, objectivec/google/protobuf/*.pbobjc.m, and objectivec/*.m except for objectivec/GPBProtocolBuffers.m to your project.

If the target is using ARC, remember to turn off ARC (-fno-objc-arc) for the .m files.

The files generated by protoc for the *.proto files (*.pbobjc.h and *.pbobjc.m) are then also added to the target.

Usage

The objects generated for messages should work like any other Objective C object. They are mutable objects, but if you don't change them, they are safe to share between threads (similar to passing an NSMutableDictionary between threads/queues; as long as no one mutates it, things are fine).

There are a few behaviors worth calling out:

A property that is type NSString* will never return nil. If the value is unset, it will return an empty string (@""). This is inpart to align things with the Protocol Buffers spec which says the default for strings is an empty string, but also so you can always safely pass them to isEqual:/compare:, etc. and have deterministic results.

A property that is type NSData* also won't return nil, it will return an empty data ([NSData data]). The reasoning is the same as for NSString not returning nil.

A property that is another GPBMessage class also will not return nil. If the field wasn't already set, you will get a instance of the correct class. This instance will be a temporary instance unless you mutate it, at which point it will be attached to its parent object. We call this pattern autocreators. Similar to NSString and NSData properties it makes things a little safer when using them with isEqual:/etc.; but more importantly, this allows you to write code that uses Objective C's property dot notation to walk into nested objects and access and/or assign things without having to check that they are not nil and create them each step along the way. You can write this:

- (void)updateRecord:(MyMessage *)msg {
  ...
  // Note: You don't have to check subMessage and otherMessage for nil and
  // alloc/init/assign them back along the way.
  msg.subMessage.otherMessage.lastName = @"Smith";
  ...
}

If you want to check if a GPBMessage property is present, there is always as has\[NAME\] property to go with the main property to check if it is set.

A property that is of an Array or Dictionary type also provides autocreator behavior and will never return nil. This provides all the same benefits you see for the message properties. Again, you can write:

- (void)updateRecord:(MyMessage *)msg {
  ...
  // Note: Just like above, you don't have to check subMessage and otherMessage
  // for nil and alloc/init/assign them back along the way. You also don't have
  // to create the siblingsArray, you can safely just append to it.
  [msg.subMessage.otherMessage.siblingsArray addObject:@"Pat"];
  ...
}

If you are inspecting a message you got from some other place (server, disk, etc), you may want to check if the Array or Dictionary has entries without causing it to be created for you. For this, there is always a \[NAME\]_Count property also provided that can return zero or the real count, but won't trigger the creation.

For primitive type fields (ints, floats, bools, enum) in messages defined in a .proto file that use proto2 syntax there are conceptual differences between having an explicit and default value. You can always get the value of the property. In the case that it hasn't been set you will get the default. In cases where you need to know whether it was set explicitly or you are just getting the default, you can use the has\[NAME\] property. If the value has been set, and you want to clear it, you can set the has\[NAME\] to NO. proto3 syntax messages do away with this concept, thus the default values are never included when the message is encoded.

The Objective C classes/enums can be used from Swift code.

Objective C Generator Proto File Options

objc_class_prefix=<prefix> (no default)

Since Objective C uses a global namespace for all of its classes, there can be collisions. This option provides a prefix that will be added to the Enums and Objects (for messages) generated from the proto. Convention is to base the prefix on the package the proto is in.

Objective C Generator protoc Options

When generating Objective C code, protoc supports a --objc_opt argument; the argument is comma-delimited name/value pairs (key=value,key2=value2). The keys are used to change the behavior during generation. The currently supported keys are:

  • generate_for_named_framework: The value used for this key will be used when generating the #import statements in the generated code. Instead of being plain #import "some/path/file.pbobjc.h" lines, they will be framework based, i.e. - #import <VALUE/file.pbobjc.h>.

    NOTE: If this is used with named_framework_to_proto_path_mappings_path, then this is effectively the default to use for everything that wasn't mapped by the other.

  • named_framework_to_proto_path_mappings_path: The value used for this key is a path to a file containing the listing of framework names and proto files. The generator uses this to decide if another proto file referenced should use a framework style import vs. a user level import (#import <FRAMEWORK/file.pbobjc.h> vs #import "dir/file.pbobjc.h").

    The format of the file is:

    • An entry is a line of frameworkName: file.proto, dir/file2.proto.
    • Comments start with #.
    • A comment can go on a line after an entry. (i.e. - frameworkName: file.proto # comment)

    Any number of files can be listed for a framework, just separate them with commas.

    There can be multiple lines listing the same frameworkName incase it has a lot of proto files included in it; and having multiple lines makes things easier to read.

Contributing

Please make updates to the tests along with changes. If just changing the runtime, the Xcode projects can be used to build and run tests. If your change also requires changes to the generated code, objectivec/DevTools/full_mac_build.sh can be used to easily rebuild and test changes. Passing -h to the script will show the addition options that could be useful.

Documentation

The complete documentation for Protocol Buffers is available via the web at:

https://developers.google.com/protocol-buffers/