OLD | NEW |
| (Empty) |
1 Protocol Buffers - Google's data interchange format | |
2 =================================================== | |
3 | |
4 [](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 6.3 (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 |