diff options
Diffstat (limited to 'objectivec/README.md')
| -rw-r--r-- | objectivec/README.md | 188 |
1 files changed, 188 insertions, 0 deletions
diff --git a/objectivec/README.md b/objectivec/README.md new file mode 100644 index 00000000..06118349 --- /dev/null +++ b/objectivec/README.md @@ -0,0 +1,188 @@ +Protocol Buffers - Google's data interchange format +=================================================== + +[](https://travis-ci.org/google/protobuf) + +Copyright 2008 Google Inc. + +This directory contains the Objective C Protocol Buffers runtime library. + +Requirements +------------ + +The Objective C implementation requires: + +- Objective C 2.0 Runtime (32bit & 64bit iOS, 64bit OS X). +- Xcode 7.0 (or later). +- The library code does *not* use ARC (for performance reasons), but it all can + be called from ARC code. + +Installation +------------ + +The full distribution pulled from github includes the sources for both the +compiler (protoc) and the runtime (this directory). To build the compiler +and run the runtime tests, you can use: + + $ objectivec/DevTools/full_mac_build.sh + +This will generate the `src/protoc` binary. + +Building +-------- + +There are two ways to include the Runtime sources in your project: + +Add `objectivec/\*.h` & `objectivec/GPBProtocolBuffers.m` to your project. + +*or* + +Add `objectivec/\*.h` & `objectivec/\*.m` except for +`objectivec/GPBProtocolBuffers.m` to your project. + + +If the target is using ARC, remember to turn off ARC (`-fno-objc-arc`) for the +`.m` files. + +The files generated by `protoc` for the `*.proto` files (`\*.pbobjc.h' and +`\*.pbobjc.m`) are then also added to the target. + +Usage +----- + +The objects generated for messages should work like any other Objective C +object. They are mutable objects, but if you don't change them, they are safe +to share between threads (similar to passing an NSMutableDictionary between +threads/queues; as long as no one mutates it, things are fine). + +There are a few behaviors worth calling out: + +A property that is type NSString\* will never return nil. If the value is +unset, it will return an empty string (@""). This is inpart to align things +with the Protocol Buffers spec which says the default for strings is an empty +string, but also so you can always safely pass them to isEqual:/compare:, etc. +and have deterministic results. + +A property that is type NSData\* also won't return nil, it will return an empty +data ([NSData data]). The reasoning is the same as for NSString not returning +nil. + +A property that is another GPBMessage class also will not return nil. If the +field wasn't already set, you will get a instance of the correct class. This +instance will be a temporary instance unless you mutate it, at which point it +will be attached to its parent object. We call this pattern *autocreators*. +Similar to NSString and NSData properties it makes things a little safer when +using them with isEqual:/etc.; but more importantly, this allows you to write +code that uses Objective C's property dot notation to walk into nested objects +and access and/or assign things without having to check that they are not nil +and create them each step along the way. You can write this: + +``` +- (void)updateRecord:(MyMessage *)msg { + ... + // Note: You don't have to check subMessage and otherMessage for nil and + // alloc/init/assign them back along the way. + msg.subMessage.otherMessage.lastName = @"Smith"; + ... +} +``` + +If you want to check if a GPBMessage property is present, there is always as +`has\[NAME\]` property to go with the main property to check if it is set. + +A property that is of an Array or Dictionary type also provides *autocreator* +behavior and will never return nil. This provides all the same benefits you +see for the message properties. Again, you can write: + +``` +- (void)updateRecord:(MyMessage *)msg { + ... + // Note: Just like above, you don't have to check subMessage and otherMessage + // for nil and alloc/init/assign them back along the way. You also don't have + // to create the siblingsArray, you can safely just append to it. + [msg.subMessage.otherMessage.siblingsArray addObject:@"Pat"]; + ... +} +``` + +If you are inspecting a message you got from some other place (server, disk, +etc), you may want to check if the Array or Dictionary has entries without +causing it to be created for you. For this, there is always a `\[NAME\]_Count` +property also provided that can return zero or the real count, but won't trigger +the creation. + +For primitive type fields (ints, floats, bools, enum) in messages defined in a +`.proto` file that use *proto2* syntax there are conceptual differences between +having an *explicit* and *default* value. You can always get the value of the +property. In the case that it hasn't been set you will get the default. In +cases where you need to know whether it was set explicitly or you are just +getting the default, you can use the `has\[NAME\]` property. If the value has +been set, and you want to clear it, you can set the `has\[NAME\]` to `NO`. +*proto3* syntax messages do away with this concept, thus the default values are +never included when the message is encoded. + +The Objective C classes/enums can be used from Swift code. + +Objective C Generator Proto File Options +---------------------------------------- + +**objc_class_prefix=\<prefix\>** (no default) + +Since Objective C uses a global namespace for all of its classes, there can +be collisions. This option provides a prefix that will be added to the Enums +and Objects (for messages) generated from the proto. Convention is to base +the prefix on the package the proto is in. + +Objective C Generator `protoc` Options +-------------------------------------- + +When generating Objective C code, `protoc` supports a `--objc_opt` argument; the +argument is comma-delimited name/value pairs (_key=value,key2=value2_). The +_keys_ are used to change the behavior during generation. The currently +supported keys are: + + * `generate_for_named_framework`: The `value` used for this key will be used + when generating the `#import` statements in the generated code. Instead + of being plain `#import "some/path/file.pbobjc.h"` lines, they will be + framework based, i.e. - `#import <VALUE/file.pbobjc.h>`. + + _NOTE:_ If this is used with `named_framework_to_proto_path_mappings_path`, + then this is effectively the _default_ to use for everything that wasn't + mapped by the other. + + * `named_framework_to_proto_path_mappings_path`: The `value` used for this key + is a path to a file containing the listing of framework names and proto + files. The generator uses this to decide if another proto file referenced + should use a framework style import vs. a user level import + (`#import <FRAMEWORK/file.pbobjc.h>` vs `#import "dir/file.pbobjc.h"`). + + The format of the file is: + * An entry is a line of `frameworkName: file.proto, dir/file2.proto`. + * Comments start with `#`. + * A comment can go on a line after an entry. + (i.e. - `frameworkName: file.proto # comment`) + + Any number of files can be listed for a framework, just separate them with + commas. + + There can be multiple lines listing the same frameworkName incase it has a + lot of proto files included in it; and having multiple lines makes things + easier to read. + +Contributing +------------ + +Please make updates to the tests along with changes. If just changing the +runtime, the Xcode projects can be used to build and run tests. If your change +also requires changes to the generated code, +`objectivec/DevTools/full_mac_build.sh` can be used to easily rebuild and test +changes. Passing `-h` to the script will show the addition options that could +be useful. + +Documentation +------------- + +The complete documentation for Protocol Buffers is available via the +web at: + + https://developers.google.com/protocol-buffers/ |