README.md
1Protocol Buffers - Google's data interchange format
2===================================================
3
4Copyright 2008 Google Inc.
5
6This directory contains the Objective C Protocol Buffers runtime library.
7
8Requirements
9------------
10
11The Objective C implementation requires:
12
13- Objective C 2.0 Runtime (32bit & 64bit iOS, 64bit OS X).
14- Xcode 10.3 (or later).
15- The library code does *not* use ARC (for performance reasons), but it all can
16 be called from ARC code.
17
18Installation
19------------
20
21The distribution pulled from github includes the sources for both the
22compiler (protoc) and the runtime (this directory). After cloning the distribution
23and needed submodules ([see the src directory's README](../src/README.md)),
24to build the compiler and run the runtime tests, you can use:
25
26 $ objectivec/DevTools/full_mac_build.sh
27
28This will generate the `src/protoc` binary.
29
30Building
31--------
32
33There are two ways to include the Runtime sources in your project:
34
35Add `objectivec/*.h`, `objectivec/google/protobuf/*.pbobjc.h`, and
36`objectivec/GPBProtocolBuffers.m` to your project.
37
38*or*
39
40Add `objectivec/*.h`, `objectivec/google/protobuf/*.pbobjc.h`,
41`objectivec/google/protobuf/*.pbobjc.m`, and `objectivec/*.m` except for
42`objectivec/GPBProtocolBuffers.m` to your project.
43
44
45If the target is using ARC, remember to turn off ARC (`-fno-objc-arc`) for the
46`.m` files.
47
48The files generated by `protoc` for the `*.proto` files (`*.pbobjc.h` and
49`*.pbobjc.m`) are then also added to the target.
50
51Usage
52-----
53
54The objects generated for messages should work like any other Objective C
55object. They are mutable objects, but if you don't change them, they are safe
56to share between threads (similar to passing an NSMutableDictionary between
57threads/queues; as long as no one mutates it, things are fine).
58
59There are a few behaviors worth calling out:
60
61A property that is type NSString\* will never return nil. If the value is
62unset, it will return an empty string (@""). This is inpart to align things
63with the Protocol Buffers spec which says the default for strings is an empty
64string, but also so you can always safely pass them to isEqual:/compare:, etc.
65and have deterministic results.
66
67A property that is type NSData\* also won't return nil, it will return an empty
68data ([NSData data]). The reasoning is the same as for NSString not returning
69nil.
70
71A property that is another GPBMessage class also will not return nil. If the
72field wasn't already set, you will get a instance of the correct class. This
73instance will be a temporary instance unless you mutate it, at which point it
74will be attached to its parent object. We call this pattern *autocreators*.
75Similar to NSString and NSData properties it makes things a little safer when
76using them with isEqual:/etc.; but more importantly, this allows you to write
77code that uses Objective C's property dot notation to walk into nested objects
78and access and/or assign things without having to check that they are not nil
79and create them each step along the way. You can write this:
80
81```
82- (void)updateRecord:(MyMessage *)msg {
83 ...
84 // Note: You don't have to check subMessage and otherMessage for nil and
85 // alloc/init/assign them back along the way.
86 msg.subMessage.otherMessage.lastName = @"Smith";
87 ...
88}
89```
90
91If you want to check if a GPBMessage property is present, there is always as
92`has\[NAME\]` property to go with the main property to check if it is set.
93
94A property that is of an Array or Dictionary type also provides *autocreator*
95behavior and will never return nil. This provides all the same benefits you
96see for the message properties. Again, you can write:
97
98```
99- (void)updateRecord:(MyMessage *)msg {
100 ...
101 // Note: Just like above, you don't have to check subMessage and otherMessage
102 // for nil and alloc/init/assign them back along the way. You also don't have
103 // to create the siblingsArray, you can safely just append to it.
104 [msg.subMessage.otherMessage.siblingsArray addObject:@"Pat"];
105 ...
106}
107```
108
109If you are inspecting a message you got from some other place (server, disk,
110etc), you may want to check if the Array or Dictionary has entries without
111causing it to be created for you. For this, there is always a `\[NAME\]_Count`
112property also provided that can return zero or the real count, but won't trigger
113the creation.
114
115For primitive type fields (ints, floats, bools, enum) in messages defined in a
116`.proto` file that use *proto2* syntax there are conceptual differences between
117having an *explicit* and *default* value. You can always get the value of the
118property. In the case that it hasn't been set you will get the default. In
119cases where you need to know whether it was set explicitly or you are just
120getting the default, you can use the `has\[NAME\]` property. If the value has
121been set, and you want to clear it, you can set the `has\[NAME\]` to `NO`.
122*proto3* syntax messages do away with this concept, thus the default values are
123never included when the message is encoded.
124
125The Objective C classes/enums can be used from Swift code.
126
127Objective C Generator Proto File Options
128----------------------------------------
129
130**objc_class_prefix=\<prefix\>** (no default)
131
132This options allow you to provide a custom prefix for all the symbols generated
133from a proto file (classes (from message), enums, the Root for extension
134support).
135
136If not set, the generation options `package_to_prefix_mappings_path` and
137`use_package_as_prefix` (documented below) controls what is used instead. Since
138Objective C uses a global namespace for all of its classes, there can be collisions.
139`use_package_as_prefix=yes` should avoid collisions since proto package are used to
140scope/name things in other languages, but this option can be used to get shorter
141names instead. Convention is to base the explicit prefix on the proto package.
142
143Objective C Generator `protoc` Options
144--------------------------------------
145
146When generating Objective C code, `protoc` supports a `--objc_opt` argument; the
147argument is comma-delimited name/value pairs (_key=value,key2=value2_). The
148_keys_ are used to change the behavior during generation. The currently
149supported keys are:
150
151 * `generate_for_named_framework`: The `value` used for this key will be used
152 when generating the `#import` statements in the generated code. Instead
153 of being plain `#import "some/path/file.pbobjc.h"` lines, they will be
154 framework based, i.e. - `#import <VALUE/file.pbobjc.h>`.
155
156 _NOTE:_ If this is used with `named_framework_to_proto_path_mappings_path`,
157 then this is effectively the _default_ to use for everything that wasn't
158 mapped by the other.
159
160 * `named_framework_to_proto_path_mappings_path`: The `value` used for this key
161 is a path to a file containing the listing of framework names and proto
162 files. The generator uses this to decide if another proto file referenced
163 should use a framework style import vs. a user level import
164 (`#import <FRAMEWORK/file.pbobjc.h>` vs `#import "dir/file.pbobjc.h"`).
165
166 The format of the file is:
167 * An entry is a line of `frameworkName: file.proto, dir/file2.proto`.
168 * Comments start with `#`.
169 * A comment can go on a line after an entry.
170 (i.e. - `frameworkName: file.proto # comment`)
171
172 Any number of files can be listed for a framework, just separate them with
173 commas.
174
175 There can be multiple lines listing the same frameworkName in case it has a
176 lot of proto files included in it; and having multiple lines makes things
177 easier to read.
178
179 * `runtime_import_prefix`: The `value` used for this key to be used as a
180 prefix on `#import`s of runtime provided headers in the generated files.
181 When integrating ObjC protos into a build system, this can be used to avoid
182 having to add the runtime directory to the header search path since the
183 generate `#import` will be more complete.
184
185 * `package_to_prefix_mappings_path`: The `value` used for this key is a
186 path to a file containing a list of proto packages and prefixes.
187 The generator will use this to locate which ObjC class prefix to use when
188 generating sources _unless_ the `objc_class_prefix` file option is set.
189 This option can be useful if multiple apps consume a common set of
190 proto files but wish to use a different prefix for the generated sources
191 between them. This option takes precedent over the `use_package_as_prefix`
192 option.
193
194 The format of the file is:
195 * An entry is a line of "package=prefix".
196 * Comments start with `#`.
197 * A comment can go on a line after a expected package/prefix pair.
198 (i.e. - "package=prefix # comment")
199 * For files that do NOT have a proto package (not recommended), an
200 entry can be made as "no_package:PATH=prefix", where PATH is the
201 path for the .proto file.
202
203 * `use_package_as_prefix` and `proto_package_prefix_exceptions_path`: The
204 `value` for `use_package_as_prefix` can be `yes` or `no`, and indicates
205 if a prefix should be derived from the proto package for all the symbols
206 for files that don't have the `objc_class_prefix` file option (mentioned
207 above). This helps ensure the symbols are more unique and means there is
208 less chance of ObjC class name collisions.
209
210 To help in migrating code to using this support,
211 `proto_package_prefix_exceptions_path` can be used to provide the path
212 to a file that contains proto package names (one per line, comments allowed
213 if prefixed with `#`). These package won't get the derived prefix, allowing
214 migrations to the behavior one proto package at a time across a code base.
215
216 `use_package_as_prefix` currently defaults to `no` (existing behavior), but
217 in the future (as a breaking change), that is likely to change since it
218 helps prepare folks before they end up using a lot of protos and getting a
219 lot of collisions.
220
221 * `headers_use_forward_declarations`: The `value` for this can be `yes` or
222 `no`, and indicates if the generated headers use forward declarations for
223 Message and Enum types from other .proto files or if the files should be
224 imported into the generated header instead.
225
226 By using forward declarations, less code is likely to recompile when the
227 files do change, but Swift generally doesn't like forward declarations and
228 will fail to include properties when the concrete definition of the type is
229 known at import time. If your proto usages span modules, this can be a
230 problem.
231
232 `headers_use_forward_declarations` currently defaults to `yes` (existing
233 behavior), but in a future release, that default may change to provide
234 better Swift support by default.
235
236Contributing
237------------
238
239Please make updates to the tests along with changes. If just changing the
240runtime, the Xcode projects can be used to build and run tests. If your change
241also requires changes to the generated code,
242`objectivec/DevTools/full_mac_build.sh` can be used to easily rebuild and test
243changes. Passing `-h` to the script will show the addition options that could
244be useful.
245
246Documentation
247-------------
248
249The complete documentation for Protocol Buffers is available via the
250web at:
251
252https://developers.google.com/protocol-buffers/
253