OLD | NEW |
(Empty) | |
| 1 Protocol Buffers - Google's data interchange format |
| 2 =================================================== |
| 3 |
| 4 [![Build Status](https://travis-ci.org/google/protobuf.svg?branch=master)](https
://travis-ci.org/google/protobuf) |
| 5 |
| 6 Copyright 2008 Google Inc. |
| 7 |
| 8 This directory contains the Objective C Protocol Buffers runtime library. |
| 9 |
| 10 Requirements |
| 11 ------------ |
| 12 |
| 13 The Objective C implemention requires: |
| 14 |
| 15 - Objective C 2.0 Runtime (32bit & 64bit iOS, 64bit OS X). |
| 16 - Xcode 7.0 (or later). |
| 17 - The library code does *not* use ARC (for performance reasons), but it all can |
| 18 be called from ARC code. |
| 19 |
| 20 Installation |
| 21 ------------ |
| 22 |
| 23 The full distribution pulled from github includes the sources for both the |
| 24 compiler (protoc) and the runtime (this directory). To build the compiler |
| 25 and run the runtime tests, you can use: |
| 26 |
| 27 $ objectivec/DevTools/full_mac_build.sh |
| 28 |
| 29 This will generate the `src/protoc` binary. |
| 30 |
| 31 Building |
| 32 -------- |
| 33 |
| 34 There are two ways to include the Runtime sources in your project: |
| 35 |
| 36 Add `objectivec/\*.h` & `objectivec/GPBProtocolBuffers.m` to your project. |
| 37 |
| 38 *or* |
| 39 |
| 40 Add `objectivec/\*.h` & `objectivec/\*.m` except for |
| 41 `objectivec/GPBProtocolBuffers.m` to your project. |
| 42 |
| 43 |
| 44 If the target is using ARC, remember to turn off ARC (`-fno-objc-arc`) for the |
| 45 `.m` files. |
| 46 |
| 47 The files generated by `protoc` for the `*.proto` files (`\*.pbobjc.h' and |
| 48 `\*.pbobjc.m`) are then also added to the target. |
| 49 |
| 50 Usage |
| 51 ----- |
| 52 |
| 53 The objects generated for messages should work like any other Objective C |
| 54 object. They are mutable objects, but if you don't change them, they are safe |
| 55 to share between threads (similar to passing an NSMutableDictionary between |
| 56 threads/queues; as long as no one mutates it, things are fine). |
| 57 |
| 58 There are a few behaviors worth calling out: |
| 59 |
| 60 A property that is type NSString\* will never return nil. If the value is |
| 61 unset, it will return an empty string (@""). This is inpart to align things |
| 62 with the Protocol Buffers spec which says the default for strings is an empty |
| 63 string, but also so you can always safely pass them to isEqual:/compare:, etc. |
| 64 and have deterministic results. |
| 65 |
| 66 A property that is type NSData\* also won't return nil, it will return an empty |
| 67 data ([NSData data]). The reasoning is the same as for NSString not returning |
| 68 nil. |
| 69 |
| 70 A property that is another GPBMessage class also will not return nil. If the |
| 71 field wasn't already set, you will get a instance of the correct class. This |
| 72 instance will be a temporary instance unless you mutate it, at which point it |
| 73 will be attached to its parent object. We call this pattern *autocreators*. |
| 74 Similar to NSString and NSData properties it makes things a little safer when |
| 75 using them with isEqual:/etc.; but more importantly, this allows you to write |
| 76 code that uses Objective C's property dot notation to walk into nested objects |
| 77 and access and/or assign things without having to check that they are not nil |
| 78 and create them each step along the way. You can write this: |
| 79 |
| 80 ``` |
| 81 - (void)updateRecord:(MyMessage *)msg { |
| 82 ... |
| 83 // Note: You don't have to check subMessage and otherMessage for nil and |
| 84 // alloc/init/assign them back along the way. |
| 85 msg.subMessage.otherMessage.lastName = @"Smith"; |
| 86 ... |
| 87 } |
| 88 ``` |
| 89 |
| 90 If you want to check if a GPBMessage property is present, there is always as |
| 91 `has\[NAME\]` property to go with the main property to check if it is set. |
| 92 |
| 93 A property that is of an Array or Dictionary type also provides *autocreator* |
| 94 behavior and will never return nil. This provides all the same benefits you |
| 95 see for the message properties. Again, you can write: |
| 96 |
| 97 ``` |
| 98 - (void)updateRecord:(MyMessage *)msg { |
| 99 ... |
| 100 // Note: Just like above, you don't have to check subMessage and otherMessage |
| 101 // for nil and alloc/init/assign them back along the way. You also don't have |
| 102 // to create the siblingsArray, you can safely just append to it. |
| 103 [msg.subMessage.otherMessage.siblingsArray addObject:@"Pat"]; |
| 104 ... |
| 105 } |
| 106 ``` |
| 107 |
| 108 If you are inspecting a message you got from some other place (server, disk, |
| 109 etc), you may want to check if the Array or Dictionary has entries without |
| 110 causing it to be created for you. For this, there is always a `\[NAME\]_Count` |
| 111 property also provided that can return zero or the real count, but won't trigger |
| 112 the creation. |
| 113 |
| 114 For primitive type fields (ints, floats, bools, enum) in messages defined in a |
| 115 `.proto` file that use *proto2* syntax there are conceptual differences between |
| 116 having an *explicit* and *default* value. You can always get the value of the |
| 117 property. In the case that it hasn't been set you will get the default. In |
| 118 cases where you need to know whether it was set explicitly or you are just |
| 119 getting the default, you can use the `has\[NAME\]` property. If the value has |
| 120 been set, and you want to clear it, you can set the `has\[NAME\]` to `NO`. |
| 121 *proto3* syntax messages do away with this concept, thus the default values are |
| 122 never included when the message is encoded. |
| 123 |
| 124 The Objective C classes/enums can be used from Swift code. |
| 125 |
| 126 Objective C Generator Options |
| 127 ----------------------------- |
| 128 |
| 129 **objc_class_prefix=\<prefix\>** (no default) |
| 130 |
| 131 Since Objective C uses a global namespace for all of its classes, there can |
| 132 be collisions. This option provides a prefix that will be added to the Enums |
| 133 and Objects (for messages) generated from the proto. Convention is to base |
| 134 the prefix on the package the proto is in. |
| 135 |
| 136 Contributing |
| 137 ------------ |
| 138 |
| 139 Please make updates to the tests along with changes. If just changing the |
| 140 runtime, the Xcode projects can be used to build and run tests. If your change |
| 141 also requires changes to the generated code, |
| 142 `objectivec/DevTools/full_mac_build.sh` can be used to easily rebuild and test |
| 143 changes. Passing `-h` to the script will show the addition options that could |
| 144 be useful. |
| 145 |
| 146 Documentation |
| 147 ------------- |
| 148 |
| 149 The complete documentation for Protocol Buffers is available via the |
| 150 web at: |
| 151 |
| 152 https://developers.google.com/protocol-buffers/ |
OLD | NEW |