From 8c65bb7c5092775f2d1fc615e5d5f3339dec1421 Mon Sep 17 00:00:00 2001 From: Max Cai Date: Thu, 10 Oct 2013 16:09:48 +0100 Subject: [PATCH] Add missing README parts for enum_style and in-repo usage Change-Id: I7934a5b0444017aeda787501ebf8d9f9ba295c73 --- java/README.txt | 54 ++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 51 insertions(+), 3 deletions(-) diff --git a/java/README.txt b/java/README.txt index adc1972cc5..3a004c7ef5 100644 --- a/java/README.txt +++ b/java/README.txt @@ -464,6 +464,7 @@ java_outer_classname -> | java_multiple_files -> true or false java_nano_generate_has -> true or false [DEPRECATED] optional_field_style -> default or accessors +enum_style -> c or java java_package: java_outer_classname: @@ -540,15 +541,61 @@ optional_field_style={default,accessors,reftypes} (default: default) mode, serialization of the proto will cause a NullPointerException. This is an intentional indicator that you must set required fields. - NOTE optional_field_style=accessors or reftypes cannot be used together with java_nano_generate_has=true. If you need the 'has' flag for any required field (you have no reason to), you can only use java_nano_generate_has=true. - -To use nano protobufs: +enum_style={c,java} (default: c) + Defines where to put the int constants generated from enum members. + + * c * + + Use C-style, so the enum constants are available at the scope where + the enum is defined. A file-scope enum's members are referenced like + 'FileOuterClass.ENUM_VALUE'; a message-scope enum's members are + referenced as 'Message.ENUM_VALUE'. The enum name is unavailable. + This complies with the Micro code generator's behavior. + + * java * + + Use Java-style, so the enum constants are available under the enum + name and referenced like 'EnumName.ENUM_VALUE' (they are still int + constants). The enum name becomes the name of a public interface, at + the scope where the enum is defined. If the enum is file-scope and + the java_multiple_files option is on, the interface will be defined + in its own file. To reduce code size, this interface should not be + implemented and ProGuard shrinking should be used, so after the Java + compiler inlines all referenced enum constants into the call sites, + the interface remains unused and can be removed by ProGuard. + + +To use nano protobufs within the Android repo: + +- Set 'LOCAL_PROTOC_OPTIMIZE_TYPE := nano' in your local .mk file. + When building a Java library or an app (package) target, the build + system will add the Java nano runtime library to the + LOCAL_STATIC_JAVA_LIBRARIES variable, so you don't need to. +- Set 'LOCAL_PROTO_JAVA_OUTPUT_PARAMS := ...' in your local .mk file + for any command-line options you need. Use commas to join multiple + options. Write all options on the same line; avoid backslash-newline + or '+=', because they will introduce spaces in the middle of your + options and the generator is not prepared to handle them. +- The options will be applied to *all* proto files in LOCAL_SRC_FILES + when you build a Java library or package. In case different options + are needed for different proto files, build separate Java libraries + and reference them in your main target. Note: you should make sure + that, for each separate target, all proto files imported from any + proto file in LOCAL_SRC_FILES are included in LOCAL_SRC_FILES. This + is because the generator has to assume that the imported files are + built using the same options, and will generate code that reference + the fields and enums from the imported files using the same code + style. +- Hint: 'include $(CLEAR_VARS)' resets all LOCAL_ variables, including + the two above. + +To use nano protobufs outside of Android repo: - Link with the generated jar file java/target/protobuf-java-2.3.0-nano.jar. @@ -559,6 +606,7 @@ java_package=src/proto/simple-data.proto|my_package,\ java_outer_classname=src/proto/simple-data.proto|OuterName:\ .' src/proto/simple-data.proto + Contributing to nano: Please add/edit tests in NanoTest.java.