diff options
Diffstat (limited to 'objectivec/README.md')
| -rw-r--r-- | objectivec/README.md | 59 |
1 files changed, 49 insertions, 10 deletions
diff --git a/objectivec/README.md b/objectivec/README.md index c7313e4f..21ac07d8 100644 --- a/objectivec/README.md +++ b/objectivec/README.md @@ -13,16 +13,17 @@ Requirements The Objective C implementation requires: - Objective C 2.0 Runtime (32bit & 64bit iOS, 64bit OS X). -- Xcode 7.0 (or later). +- Xcode 8.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: +The distribution pulled from github includes the sources for both the +compiler (protoc) and the runtime (this directory). After cloning the distribution +and needed submodules ([see the src directory's README](../src/README.md)), +to build the compiler and run the runtime tests, you can use: $ objectivec/DevTools/full_mac_build.sh @@ -33,19 +34,21 @@ Building There are two ways to include the Runtime sources in your project: -Add `objectivec/\*.h` & `objectivec/GPBProtocolBuffers.m` to your project. +Add `objectivec/*.h`, `objectivec/google/protobuf/*.pbobjc.h`, and +`objectivec/GPBProtocolBuffers.m` to your project. *or* -Add `objectivec/\*.h` & `objectivec/\*.m` except for +Add `objectivec/*.h`, `objectivec/google/protobuf/*.pbobjc.h`, +`objectivec/google/protobuf/*.pbobjc.m`, and `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. +The files generated by `protoc` for the `*.proto` files (`*.pbobjc.h` and +`*.pbobjc.m`) are then also added to the target. Usage ----- @@ -123,8 +126,8 @@ never included when the message is encoded. The Objective C classes/enums can be used from Swift code. -Objective C Generator Options ------------------------------ +Objective C Generator Proto File Options +---------------------------------------- **objc_class_prefix=\<prefix\>** (no default) @@ -133,6 +136,42 @@ 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 ------------ |