Index: third_party/protobuf/objectivec/README.md |
diff --git a/third_party/protobuf/objectivec/README.md b/third_party/protobuf/objectivec/README.md |
new file mode 100644 |
index 0000000000000000000000000000000000000000..452feca466a8898ac4a82e5b1adf5e47fc323d73 |
--- /dev/null |
+++ b/third_party/protobuf/objectivec/README.md |
@@ -0,0 +1,152 @@ |
+Protocol Buffers - Google's data interchange format |
+=================================================== |
+ |
+[![Build Status](https://travis-ci.org/google/protobuf.svg?branch=master)](https://travis-ci.org/google/protobuf) |
+ |
+Copyright 2008 Google Inc. |
+ |
+This directory contains the Objective C Protocol Buffers runtime library. |
+ |
+Requirements |
+------------ |
+ |
+The Objective C implemention requires: |
+ |
+- Objective C 2.0 Runtime (32bit & 64bit iOS, 64bit OS X). |
+- Xcode 7.0 (or later). |
+- The library code does *not* use ARC (for performance reasons), but it all can |
+ be called from ARC code. |
+ |
+Installation |
+------------ |
+ |
+The full distribution pulled from github includes the sources for both the |
+compiler (protoc) and the runtime (this directory). 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/GPBProtocolBuffers.m` to your project. |
+ |
+*or* |
+ |
+Add `objectivec/\*.h` & `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 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. |
+ |
+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/ |