1 Protocol Buffers - Google's data interchange format 2 =================================================== 3 4 [](https://travis-ci.org/google/protobuf) 5 6 Copyright 2008 Google Inc. 7 8 This directory contains the Java Protocol Buffers runtime library. 9 10 Installation - With Maven 11 ========================= 12 13 The Protocol Buffers build is managed using Maven. If you would 14 rather build without Maven, see below. 15 16 1) Install Apache Maven if you don't have it: 17 18 http://maven.apache.org/ 19 20 2) Build the C++ code, or obtain a binary distribution of protoc (see 21 the toplevel [README.md](../README.md)). If you install a binary 22 distribution, make sure that it is the same version as this package. 23 If in doubt, run: 24 25 $ protoc --version 26 27 You will need to place the protoc executable in ../src. (If you 28 built it yourself, it should already be there.) 29 30 3) Run the tests: 31 32 $ mvn test 33 34 If some tests fail, this library may not work correctly on your 35 system. Continue at your own risk. 36 37 4) Install the library into your Maven repository: 38 39 $ mvn install 40 41 5) If you do not use Maven to manage your own build, you can build a 42 .jar file to use: 43 44 $ mvn package 45 46 The .jar will be placed in the "target" directory. 47 48 The above instructions will install 3 maven artifacts: 49 50 * protobuf-java: The core Java Protocol Buffers library. Most users only 51 need this artifact. 52 * protobuf-lite: The lite version of core Java Protobuf Buffers library. It 53 is a subset of the core library and is used together with 54 the 'lite' code generator flag to reduce generated code size 55 for mobile. 56 * protobuf-java-util: Utilities to work with protos. It contains JSON support 57 as well as utilities to work with proto3 well-known 58 types. 59 60 Installation - Without Maven 61 ============================ 62 63 If you would rather not install Maven to build the library, you may 64 follow these instructions instead. Note that these instructions skip 65 running unit tests and only describes how to install the core protobuf 66 library (without the util package). 67 68 1) Build the C++ code, or obtain a binary distribution of protoc. If 69 you install a binary distribution, make sure that it is the same 70 version as this package. If in doubt, run: 71 72 $ protoc --version 73 74 If you built the C++ code without installing, the compiler binary 75 should be located in ../src. 76 77 2) Invoke protoc to build DescriptorProtos.java: 78 79 $ protoc --java_out=core/src/main/java -I../src \ 80 ../src/google/protobuf/descriptor.proto 81 82 3) Compile the code in core/src/main/java using whatever means you prefer. 83 84 4) Install the classes wherever you prefer. 85 86 Compatibility Notice 87 ==================== 88 89 * Protobuf minor version releases are backwards-compatible. If your code 90 can build/run against the old version, it's expected to build/run against 91 the new version as well. Both binary compatibility and source compatibility 92 are guaranteed for minor version releases if the user follows the guideline 93 described in this section. 94 95 * Protobuf major version releases may also be backwards-compatbile with the 96 last release of the previous major version. See the release notice for more 97 details. 98 99 * APIs marked with the @ExperimentalApi annotation are subject to change. They 100 can be modified in any way, or even removed, at any time. Don't use them if 101 compatibility is needed. If your code is a library itself (i.e. it is used on 102 the CLASSPATH of users outside your own control), you should not use 103 experimental APIs, unless you repackage them (e.g. using ProGuard). 104 105 * Deprecated non-experimental APIs will be removed two years after the release 106 in which they are first deprecated. You must fix your references before this 107 time. If you don't, any manner of breakage could result (you are not 108 guaranteed a compilation error). 109 110 * Protobuf message interfaces/classes are designed to be subclassed by protobuf 111 generated code only. Do not subclass these message interfaces/classes 112 yourself. We may add new methods to the message interfaces/classes which will 113 break your own subclasses. 114 115 * Don't use any method/class that is marked as "used by generated code only". 116 Such methods/classes are subject to change. 117 118 * Protobuf LITE runtime APIs are not stable yet. They are subject to change even 119 in minor version releases. 120 121 Documentation 122 ============= 123 124 The complete documentation for Protocol Buffers is available via the 125 web at: 126 127 https://developers.google.com/protocol-buffers/ 128
