Index: third_party/protobuf/java/README.md |
diff --git a/third_party/protobuf/java/README.md b/third_party/protobuf/java/README.md |
index 060d9ac6b11534bb6c4bd8b0a14173759da6f10f..0e0fba647ae1867f0a98aafc1efd0ad0fb708b87 100644 |
--- a/third_party/protobuf/java/README.md |
+++ b/third_party/protobuf/java/README.md |
@@ -17,9 +17,10 @@ rather build without Maven, see below. |
http://maven.apache.org/ |
-2) Build the C++ code, or obtain a binary distribution of protoc. If |
- you install a binary distribution, make sure that it is the same |
- version as this package. If in doubt, run: |
+2) Build the C++ code, or obtain a binary distribution of protoc (see |
+ the toplevel [README.md](../README.md)). If you install a binary |
+ distribution, make sure that it is the same version as this package. |
+ If in doubt, run: |
$ protoc --version |
@@ -44,36 +45,25 @@ rather build without Maven, see below. |
The .jar will be placed in the "target" directory. |
-Installation - 'Lite' Version - With Maven |
-========================================== |
- |
-Building the 'lite' version of the Java Protocol Buffers library is |
-the same as building the full version, except that all commands are |
-run using the 'lite' profile. (see |
-http://maven.apache.org/guides/introduction/introduction-to-profiles.html) |
- |
-E.g. to install the lite version of the jar, you would run: |
+The above instructions will install 3 maven artifacts: |
- $ mvn install -P lite |
- |
-The resulting artifact has the 'lite' classifier. To reference it |
-for dependency resolution, you would specify it as: |
- |
-``` |
- <dependency> |
- <groupId>com.google.protobuf</groupId> |
- <artifactId>protobuf-java</artifactId> |
- <version>${version}</version> |
- <classifier>lite</classifier> |
- </dependency> |
-``` |
+ * protobuf-java: The core Java Protocol Buffers library. Most users only |
+ need this artifact. |
+ * protobuf-lite: The lite version of core Java Protobuf Buffers library. It |
+ is a subset of the core library and is used together with |
+ the 'lite' code generator flag to reduce generated code size |
+ for mobile. |
+ * protobuf-java-util: Utilities to work with protos. It contains JSON support |
+ as well as utilities to work with proto3 well-known |
+ types. |
Installation - Without Maven |
============================ |
If you would rather not install Maven to build the library, you may |
follow these instructions instead. Note that these instructions skip |
-running unit tests. |
+running unit tests and only describes how to install the core protobuf |
+library (without the util package). |
1) Build the C++ code, or obtain a binary distribution of protoc. If |
you install a binary distribution, make sure that it is the same |
@@ -86,15 +76,50 @@ running unit tests. |
2) Invoke protoc to build DescriptorProtos.java: |
- $ protoc --java_out=src/main/java -I../src \ |
+ $ protoc --java_out=core/src/main/java -I../src \ |
../src/google/protobuf/descriptor.proto |
-3) Compile the code in src/main/java using whatever means you prefer. |
+3) Compile the code in core/src/main/java using whatever means you prefer. |
4) Install the classes wherever you prefer. |
-Usage |
-===== |
+Compatibility Notice |
+==================== |
+ |
+* Protobuf minor version releases are backwards-compatible. If your code |
+ can build/run against the old version, it's expected to build/run against |
+ the new version as well. Both binary compatibility and source compatibility |
+ are guaranteed for minor version releases if the user follows the guideline |
+ described in this section. |
+ |
+* Protobuf major version releases may also be backwards-compatbile with the |
+ last release of the previous major version. See the release notice for more |
+ details. |
+ |
+* APIs marked with the @ExperimentalApi annotation are subject to change. They |
+ can be modified in any way, or even removed, at any time. Don't use them if |
+ compatibility is needed. If your code is a library itself (i.e. it is used on |
+ the CLASSPATH of users outside your own control), you should not use |
+ experimental APIs, unless you repackage them (e.g. using ProGuard). |
+ |
+* Deprecated non-experimental APIs will be removed two years after the release |
+ in which they are first deprecated. You must fix your references before this |
+ time. If you don't, any manner of breakage could result (you are not |
+ guaranteed a compilation error). |
+ |
+* Protobuf message interfaces/classes are designed to be subclassed by protobuf |
+ generated code only. Do not subclass these message interfaces/classes |
+ yourself. We may add new methods to the message interfaces/classes which will |
+ break your own subclasses. |
+ |
+* Don't use any method/class that is marked as "used by generated code only". |
+ Such methods/classes are subject to change. |
+ |
+* Protobuf LITE runtime APIs are not stable yet. They are subject to change even |
+ in minor version releases. |
+ |
+Documentation |
+============= |
The complete documentation for Protocol Buffers is available via the |
web at: |