README.md
1Protocol Buffers - Google's data interchange format
2===================================================
3
4[](https://fusion.corp.google.com/projectanalysis/current/KOKORO/prod:protobuf%2Fgithub%2Fmaster%2Fmacos%2Fobjectivec_cocoapods_integration%2Fcontinuous) [](https://fusion.corp.google.com/projectanalysis/current/KOKORO/prod:protobuf%2Fgithub%2Fmaster%2Fmacos%2Fobjectivec_ios_debug%2Fcontinuous) [](https://fusion.corp.google.com/projectanalysis/current/KOKORO/prod:protobuf%2Fgithub%2Fmaster%2Fmacos%2Fobjectivec_ios_release%2Fcontinuous) [](https://fusion.corp.google.com/projectanalysis/current/KOKORO/prod:protobuf%2Fgithub%2Fmaster%2Fmacos%2Fobjectivec_osx%2Fcontinuous)
5
6Copyright 2008 Google Inc.
7
8This directory contains the Objective C Protocol Buffers runtime library.
9
10Requirements
11------------
12
13The Objective C implementation requires:
14
15- Objective C 2.0 Runtime (32bit & 64bit iOS, 64bit OS X).
16- Xcode 10.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
20Installation
21------------
22
23The distribution pulled from github includes the sources for both the
24compiler (protoc) and the runtime (this directory). After cloning the distribution
25and needed submodules ([see the src directory's README](../src/README.md)),
26to build the compiler and run the runtime tests, you can use:
27
28 $ objectivec/DevTools/full_mac_build.sh
29
30This will generate the `src/protoc` binary.
31
32Building
33--------
34
35There are two ways to include the Runtime sources in your project:
36
37Add `objectivec/*.h`, `objectivec/google/protobuf/*.pbobjc.h`, and
38`objectivec/GPBProtocolBuffers.m` to your project.
39
40*or*
41
42Add `objectivec/*.h`, `objectivec/google/protobuf/*.pbobjc.h`,
43`objectivec/google/protobuf/*.pbobjc.m`, and `objectivec/*.m` except for
44`objectivec/GPBProtocolBuffers.m` to your project.
45
46
47If the target is using ARC, remember to turn off ARC (`-fno-objc-arc`) for the
48`.m` files.
49
50The files generated by `protoc` for the `*.proto` files (`*.pbobjc.h` and
51`*.pbobjc.m`) are then also added to the target.
52
53Usage
54-----
55
56The objects generated for messages should work like any other Objective C
57object. They are mutable objects, but if you don't change them, they are safe
58to share between threads (similar to passing an NSMutableDictionary between
59threads/queues; as long as no one mutates it, things are fine).
60
61There are a few behaviors worth calling out:
62
63A property that is type NSString\* will never return nil. If the value is
64unset, it will return an empty string (@""). This is inpart to align things
65with the Protocol Buffers spec which says the default for strings is an empty
66string, but also so you can always safely pass them to isEqual:/compare:, etc.
67and have deterministic results.
68
69A property that is type NSData\* also won't return nil, it will return an empty
70data ([NSData data]). The reasoning is the same as for NSString not returning
71nil.
72
73A property that is another GPBMessage class also will not return nil. If the
74field wasn't already set, you will get a instance of the correct class. This
75instance will be a temporary instance unless you mutate it, at which point it
76will be attached to its parent object. We call this pattern *autocreators*.
77Similar to NSString and NSData properties it makes things a little safer when
78using them with isEqual:/etc.; but more importantly, this allows you to write
79code that uses Objective C's property dot notation to walk into nested objects
80and access and/or assign things without having to check that they are not nil
81and create them each step along the way. You can write this:
82
83```
84- (void)updateRecord:(MyMessage *)msg {
85 ...
86 // Note: You don't have to check subMessage and otherMessage for nil and
87 // alloc/init/assign them back along the way.
88 msg.subMessage.otherMessage.lastName = @"Smith";
89 ...
90}
91```
92
93If you want to check if a GPBMessage property is present, there is always as
94`has\[NAME\]` property to go with the main property to check if it is set.
95
96A property that is of an Array or Dictionary type also provides *autocreator*
97behavior and will never return nil. This provides all the same benefits you
98see for the message properties. Again, you can write:
99
100```
101- (void)updateRecord:(MyMessage *)msg {
102 ...
103 // Note: Just like above, you don't have to check subMessage and otherMessage
104 // for nil and alloc/init/assign them back along the way. You also don't have
105 // to create the siblingsArray, you can safely just append to it.
106 [msg.subMessage.otherMessage.siblingsArray addObject:@"Pat"];
107 ...
108}
109```
110
111If you are inspecting a message you got from some other place (server, disk,
112etc), you may want to check if the Array or Dictionary has entries without
113causing it to be created for you. For this, there is always a `\[NAME\]_Count`
114property also provided that can return zero or the real count, but won't trigger
115the creation.
116
117For primitive type fields (ints, floats, bools, enum) in messages defined in a
118`.proto` file that use *proto2* syntax there are conceptual differences between
119having an *explicit* and *default* value. You can always get the value of the
120property. In the case that it hasn't been set you will get the default. In
121cases where you need to know whether it was set explicitly or you are just
122getting the default, you can use the `has\[NAME\]` property. If the value has
123been set, and you want to clear it, you can set the `has\[NAME\]` to `NO`.
124*proto3* syntax messages do away with this concept, thus the default values are
125never included when the message is encoded.
126
127The Objective C classes/enums can be used from Swift code.
128
129Objective C Generator Proto File Options
130----------------------------------------
131
132**objc_class_prefix=\<prefix\>** (no default)
133
134Since Objective C uses a global namespace for all of its classes, there can
135be collisions. This option provides a prefix that will be added to the Enums
136and Objects (for messages) generated from the proto. Convention is to base
137the prefix on the package the proto is in.
138
139Objective C Generator `protoc` Options
140--------------------------------------
141
142When generating Objective C code, `protoc` supports a `--objc_opt` argument; the
143argument is comma-delimited name/value pairs (_key=value,key2=value2_). The
144_keys_ are used to change the behavior during generation. The currently
145supported keys are:
146
147 * `generate_for_named_framework`: The `value` used for this key will be used
148 when generating the `#import` statements in the generated code. Instead
149 of being plain `#import "some/path/file.pbobjc.h"` lines, they will be
150 framework based, i.e. - `#import <VALUE/file.pbobjc.h>`.
151
152 _NOTE:_ If this is used with `named_framework_to_proto_path_mappings_path`,
153 then this is effectively the _default_ to use for everything that wasn't
154 mapped by the other.
155
156 * `named_framework_to_proto_path_mappings_path`: The `value` used for this key
157 is a path to a file containing the listing of framework names and proto
158 files. The generator uses this to decide if another proto file referenced
159 should use a framework style import vs. a user level import
160 (`#import <FRAMEWORK/file.pbobjc.h>` vs `#import "dir/file.pbobjc.h"`).
161
162 The format of the file is:
163 * An entry is a line of `frameworkName: file.proto, dir/file2.proto`.
164 * Comments start with `#`.
165 * A comment can go on a line after an entry.
166 (i.e. - `frameworkName: file.proto # comment`)
167
168 Any number of files can be listed for a framework, just separate them with
169 commas.
170
171 There can be multiple lines listing the same frameworkName incase it has a
172 lot of proto files included in it; and having multiple lines makes things
173 easier to read.
174
175 * `runtime_import_prefix`: The `value` used for this key to be used as a
176 prefix on `#import`s of runtime provided headers in the generated files.
177 When integrating ObjC protos into a build system, this can be used to avoid
178 having to add the runtime directory to the header search path since the
179 generate `#import` will be more complete.
180
181Contributing
182------------
183
184Please make updates to the tests along with changes. If just changing the
185runtime, the Xcode projects can be used to build and run tests. If your change
186also requires changes to the generated code,
187`objectivec/DevTools/full_mac_build.sh` can be used to easily rebuild and test
188changes. Passing `-h` to the script will show the addition options that could
189be useful.
190
191Documentation
192-------------
193
194The complete documentation for Protocol Buffers is available via the
195web at:
196
197 https://developers.google.com/protocol-buffers/
198
){kind=link}
){kind=link}
){kind=link}
){kind=link}