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