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 13.3.1 (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 `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 115All message fields *always* have a value when accessed. For primitive type 116fields (ints, floats, bools, enum) there the concept of *presence*, that allows 117you to tell the difference between when the field is the *default* value because 118it *was not* set and when it *was* set, but *explicitly* to the *default* 119value for the field. For fields with that do support *presence*, you can test 120if the value was *explicitly* set via the `has\[NAME\]` property. If the value 121has been set, and you want to clear it, you can set the `has\[NAME\]` to `NO`. 122 123The Objective C classes/enums can be used from Swift code. 124 125Objective C Generator Proto File Options 126---------------------------------------- 127 128**objc_class_prefix=\<prefix\>** (no default) 129 130This options allow you to provide a custom prefix for all the symbols generated 131from a proto file (classes (from message), enums, the Root for extension 132support). 133 134If not set, the generation options `package_to_prefix_mappings_path` and 135`use_package_as_prefix` (documented below) controls what is used instead. Since 136Objective C uses a global namespace for all of its classes, there can be collisions. 137`use_package_as_prefix=yes` should avoid collisions since proto package are used to 138scope/name things in other languages, but this option can be used to get shorter 139names instead. Convention is to base the explicit prefix on the proto package. 140 141Objective C Generator `protoc` Options 142-------------------------------------- 143 144When generating Objective C code, `protoc` supports a `--objc_opt` argument; the 145argument is comma-delimited name/value pairs (_key=value,key2=value2_). The 146_keys_ are used to change the behavior during generation. The currently 147supported keys are: 148 149 * `generate_for_named_framework`: The `value` used for this key will be used 150 when generating the `#import` statements in the generated code. Instead 151 of being plain `#import "some/path/file.pbobjc.h"` lines, they will be 152 framework based, i.e. - `#import <VALUE/file.pbobjc.h>`. 153 154 _NOTE:_ If this is used with `named_framework_to_proto_path_mappings_path`, 155 then this is effectively the _default_ to use for everything that wasn't 156 mapped by the other. 157 158 * `named_framework_to_proto_path_mappings_path`: The `value` used for this key 159 is a path to a file containing the listing of framework names and proto 160 files. The generator uses this to decide if another proto file referenced 161 should use a framework style import vs. a user level import 162 (`#import <FRAMEWORK/file.pbobjc.h>` vs `#import "dir/file.pbobjc.h"`). 163 164 The format of the file is: 165 * An entry is a line of `frameworkName: file.proto, dir/file2.proto`. 166 * Comments start with `#`. 167 * A comment can go on a line after an entry. 168 (i.e. - `frameworkName: file.proto # comment`) 169 170 Any number of files can be listed for a framework, just separate them with 171 commas. 172 173 There can be multiple lines listing the same frameworkName in case it has a 174 lot of proto files included in it; and having multiple lines makes things 175 easier to read. 176 177 * `runtime_import_prefix`: The `value` used for this key to be used as a 178 prefix on `#import`s of runtime provided headers in the generated files. 179 When integrating ObjC protos into a build system, this can be used to avoid 180 having to add the runtime directory to the header search path since the 181 generate `#import` will be more complete. 182 183 * `package_to_prefix_mappings_path`: The `value` used for this key is a 184 path to a file containing a list of proto packages and prefixes. 185 The generator will use this to locate which ObjC class prefix to use when 186 generating sources _unless_ the `objc_class_prefix` file option is set. 187 This option can be useful if multiple apps consume a common set of 188 proto files but wish to use a different prefix for the generated sources 189 between them. This option takes precedent over the `use_package_as_prefix` 190 option. 191 192 The format of the file is: 193 * An entry is a line of "package=prefix". 194 * Comments start with `#`. 195 * A comment can go on a line after a expected package/prefix pair. 196 (i.e. - "package=prefix # comment") 197 * For files that do NOT have a proto package (not recommended), an 198 entry can be made as "no_package:PATH=prefix", where PATH is the 199 path for the .proto file. 200 201 * `use_package_as_prefix`, `package_as_prefix_forced_prefix` and 202 `proto_package_prefix_exceptions_path`: The `value` for 203 `use_package_as_prefix` can be `yes` or `no`, and indicates if a prefix 204 should be derived from the proto package for all the symbols for files that 205 don't have the `objc_class_prefix` file option (mentioned above). This helps 206 ensure the symbols are more unique and means there is less chance of ObjC 207 class name collisions. 208 209 To help in migrating code to using this support, 210 `proto_package_prefix_exceptions_path` can be used to provide the path 211 to a file that contains proto package names (one per line, comments allowed 212 if prefixed with `#`). These package won't get the derived prefix, allowing 213 migrations to the behavior one proto package at a time across a code base. 214 215 `package_as_prefix_forced_prefix` can be used to provide a value that will 216 be used before all prefixes derived from the packages to help group all of 217 these types with a common prefix. Thus it only makes sense to use it when 218 `use_package_as_prefix` is also enabled. For example, setting this to 219 "XYZ\_" and generating a file with the package "something" defining 220 "MyMessage", would have Objective-C class be `XYZ_Something_MyMessage`. 221 222 `use_package_as_prefix` currently defaults to `no` (existing behavior), but 223 that could change in the future as it helps avoid collisions when more 224 protos get added to the build. Note that this would be a breaking change. 225 226 * `headers_use_forward_declarations`: The `value` for this can be `yes` or 227 `no`, and indicates if the generated headers use forward declarations for 228 Message and Enum types from other .proto files or if the files should be 229 imported into the generated header instead. 230 231 By using forward declarations, less code is likely to recompile when the 232 files do change, but Swift generally doesn't like forward declarations and 233 will fail to include properties when the concrete definition of the type is 234 known at import time. If your proto usages span modules, this can be a 235 problem. 236 237 `headers_use_forward_declarations` currently defaults to `yes` (existing 238 behavior), but in a future release, that default may change to provide 239 better Swift support by default. 240 241Contributing 242------------ 243 244Please make updates to the tests along with changes. If just changing the 245runtime, the Xcode projects can be used to build and run tests. If your change 246also requires changes to the generated code, 247`objectivec/DevTools/full_mac_build.sh` can be used to easily rebuild and test 248changes. Passing `-h` to the script will show the addition options that could 249be useful. 250 251Documentation 252------------- 253 254The complete documentation for Protocol Buffers is available via the 255web at: 256 257https://developers.google.com/protocol-buffers/ 258