1# Protocol Buffers - Google's data interchange format 2 3Copyright 2008 Google Inc. 4 5https://developers.google.com/protocol-buffers/ 6 7## Use Java Protocol Buffers 8 9To use protobuf in Java, first obtain the protocol compiler (a.k.a., protoc, 10see instructions in the toplevel [README.md](../README.md)) and use it to 11generate Java code for your .proto files: 12 13 $ protoc --java_out=${OUTPUT_DIR} path/to/your/proto/file 14 15Include the generated Java files in your project and add a dependency on the 16protobuf Java runtime. 17 18### Maven 19 20If you are using Maven, use the following: 21 22```xml 23<dependency> 24 <groupId>com.google.protobuf</groupId> 25 <artifactId>protobuf-java</artifactId> 26 <version><!--version--></version> 27</dependency> 28``` 29 30And **replace `<!--version-->` with a version from the 31[Maven Protocol Buffers Repository](https://mvnrepository.com/artifact/com.google.protobuf/protobuf-java).** 32For example, `3.25.3`. 33 34Make sure the version number of the runtime matches (or is newer than) the 35version number of the protoc. 36 37If you want to use features like protobuf JsonFormat, add a dependency on the 38protobuf-java-util package: 39 40```xml 41<dependency> 42 <groupId>com.google.protobuf</groupId> 43 <artifactId>protobuf-java-util</artifactId> 44 <version><!--version--></version> 45</dependency> 46``` 47 48### Use Java Protocol Buffers on Android 49 50For Android users, it's recommended to use protobuf Java Lite runtime because 51of its smaller code size. Java Lite runtime also works better with Proguard 52because it doesn't rely on Java reflection and is optimized to allow as much 53code stripping as possible. You can following these [instructions to use Java 54Lite runtime](lite.md). 55 56### Use Java Protocol Buffers with Bazel 57 58Bazel has native build rules to work with protobuf. For Java, you can use the 59`java_proto_library` rule for server and the `java_lite_proto_library` rule 60for Android. Check out [our build files examples](../examples/BUILD) to learn 61how to use them. 62 63## Build from Source 64 65Most users should follow the instructions above to use protobuf Java runtime. 66If you are contributing code to protobuf or want to use a protobuf version 67that hasn't been officially released yet, you can follow the instructions 68below to build protobuf from source code. 69 70### Build from Source 71 72You may follow these instructions to build from source. This does not require 73Maven to be installed. Note that these instructions skip running unit tests and 74only describes how to install the core protobuf library (without the util 75package). 76 771) Build the C++ code, or obtain a binary distribution of protoc (see 78 the toplevel [README.md](../README.md)). If you install a binary 79 distribution, make sure that it is the same version as this package. 80 If in doubt, run: 81 82 $ protoc --version 83 84 If you built the C++ code without installing, the compiler binary 85 should be located in ../src. 86 872) Invoke protoc to build DescriptorProtos.java: 88 89 $ protoc --java_out=core/src/main/java -I../src \ 90 ../src/google/protobuf/descriptor.proto 91 923) Compile the code in core/src/main/java using whatever means you prefer. 93 944) Install the classes wherever you prefer. 95 96### Build from Source - With Maven 97 98WARNING: Building from source with Maven is deprecated and will be removed in the 4.28.x release. 99 1001) Install Apache Maven if you don't have it: 101 102 http://maven.apache.org/ 103 1042) Build the C++ code, or obtain a binary distribution of protoc (see 105 the toplevel [README.md](../README.md)). If you install a binary 106 distribution, make sure that it is the same version as this package. 107 If in doubt, run: 108 109 $ protoc --version 110 111 You will need to place the protoc executable in ../src. (If you 112 built it yourself, it should already be there.) 113 1143) Run the tests: 115 116 $ mvn test 117 118 If some tests fail, this library may not work correctly on your 119 system. Continue at your own risk. 120 1214) Install the library into your Maven repository: 122 123 $ mvn install 124 1255) If you do not use Maven to manage your own build, you can build a 126 .jar file to use: 127 128 $ mvn package 129 130 The .jar will be placed in the "target" directory. 131 132The above instructions will install 2 maven artifacts: 133 134 * protobuf-java: The core Java Protocol Buffers library. Most users only 135 need this artifact. 136 * protobuf-java-util: Utilities to work with protos. It contains JSON support 137 as well as utilities to work with proto3 well-known 138 types. 139 140## Compatibility Notice 141 142* Protobuf minor version releases are backwards-compatible. If your code 143 can build/run against the old version, it's expected to build/run against 144 the new version as well. Both binary compatibility and source compatibility 145 are guaranteed for minor version releases if the user follows the guideline 146 described in this section. 147 148* Protobuf major version releases may also be backwards-compatible with the 149 last release of the previous major version. See the release notice for more 150 details. 151 152* APIs marked with the @ExperimentalApi annotation are subject to change. They 153 can be modified in any way, or even removed, at any time. Don't use them if 154 compatibility is needed. If your code is a library itself (i.e. it is used on 155 the CLASSPATH of users outside your own control), you should not use 156 experimental APIs, unless you repackage them (e.g. using ProGuard). 157 158* Deprecated non-experimental APIs will be removed two years after the release 159 in which they are first deprecated. You must fix your references before this 160 time. If you don't, any manner of breakage could result (you are not 161 guaranteed a compilation error). 162 163* Protobuf message interfaces/classes are designed to be subclassed by protobuf 164 generated code only. Do not subclass these message interfaces/classes 165 yourself. We may add new methods to the message interfaces/classes which will 166 break your own subclasses. 167 168* Don't use any method/class that is marked as "used by generated code only". 169 Such methods/classes are subject to change. 170 171* Protobuf LITE runtime APIs are not stable yet. They are subject to change even 172 in minor version releases. 173 174## Documentation 175 176The complete documentation for Protocol Buffers is available via the 177web at: 178 179 https://developers.google.com/protocol-buffers/ 180 181## Kotlin Protocol Buffers 182 183Code to support more idiomatic Kotlin protocol buffers has been added to the 184repository, and Kotlin support will be launched in the next numbered release. 185