README.md
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>3.6.1</version>
27</dependency>
28```
29
30Make sure the version number of the runtime matches (or is newer than) the
31version number of the protoc.
32
33If you want to use features like protobuf JsonFormat, add a dependency on the
34protobuf-java-util package:
35
36```xml
37<dependency>
38 <groupId>com.google.protobuf</groupId>
39 <artifactId>protobuf-java-util</artifactId>
40 <version>3.6.1</version>
41</dependency>
42```
43
44### Gradle
45
46If you are using Gradle, add the following to your `build.gradle` file's dependencies:
47```
48 compile 'com.google.protobuf:protobuf-java:3.6.1'
49```
50Again, be sure to check that the version number maches (or is newer than) the version number of protoc that you are using.
51
52### Use Java Protocol Buffers on Android
53
54For Android users, it's recommended to use protobuf Java Lite runtime because
55of its smaller code size. Java Lite runtime also works better with Proguard
56because it doesn't rely on Java reflection and is optimized to allow as much
57code stripping as possible. You can following these [instructions to use Java
58Lite runtime](lite.md).
59
60### Use Java Protocol Buffers with Bazel
61
62Bazel has native build rules to work with protobuf. For Java, you can use the
63`java_proto_library` rule for server and the `java_lite_proto_library` rule
64for Android. Check out [our build files examples](../examples/BUILD) to learn
65how to use them.
66
67## Build from Source
68
69Most users should follow the instructions above to use protobuf Java runtime.
70If you are contributing code to protobuf or want to use a protobuf version
71that hasn't been officially released yet, you can folllow the instructions
72below to build protobuf from source code.
73
74### Build from Source - With Maven
75
761) Install Apache Maven if you don't have it:
77
78 http://maven.apache.org/
79
802) Build the C++ code, or obtain a binary distribution of protoc (see
81 the toplevel [README.md](../README.md)). If you install a binary
82 distribution, make sure that it is the same version as this package.
83 If in doubt, run:
84
85 $ protoc --version
86
87 You will need to place the protoc executable in ../src. (If you
88 built it yourself, it should already be there.)
89
903) Run the tests:
91
92 $ mvn test
93
94 If some tests fail, this library may not work correctly on your
95 system. Continue at your own risk.
96
974) Install the library into your Maven repository:
98
99 $ mvn install
100
1015) If you do not use Maven to manage your own build, you can build a
102 .jar file to use:
103
104 $ mvn package
105
106 The .jar will be placed in the "target" directory.
107
108The above instructions will install 2 maven artifacts:
109
110 * protobuf-java: The core Java Protocol Buffers library. Most users only
111 need this artifact.
112 * protobuf-java-util: Utilities to work with protos. It contains JSON support
113 as well as utilities to work with proto3 well-known
114 types.
115
116### Build from Source - Without Maven
117
118If you would rather not install Maven to build the library, you may
119follow these instructions instead. Note that these instructions skip
120running unit tests and only describes how to install the core protobuf
121library (without the util package).
122
1231) Build the C++ code, or obtain a binary distribution of protoc. If
124 you install a binary distribution, make sure that it is the same
125 version as this package. If in doubt, run:
126
127 $ protoc --version
128
129 If you built the C++ code without installing, the compiler binary
130 should be located in ../src.
131
1322) Invoke protoc to build DescriptorProtos.java:
133
134 $ protoc --java_out=core/src/main/java -I../src \
135 ../src/google/protobuf/descriptor.proto
136
1373) Compile the code in core/src/main/java using whatever means you prefer.
138
1394) Install the classes wherever you prefer.
140
141## Compatibility Notice
142
143* Protobuf minor version releases are backwards-compatible. If your code
144 can build/run against the old version, it's expected to build/run against
145 the new version as well. Both binary compatibility and source compatibility
146 are guaranteed for minor version releases if the user follows the guideline
147 described in this section.
148
149* Protobuf major version releases may also be backwards-compatbile with the
150 last release of the previous major version. See the release notice for more
151 details.
152
153* APIs marked with the @ExperimentalApi annotation are subject to change. They
154 can be modified in any way, or even removed, at any time. Don't use them if
155 compatibility is needed. If your code is a library itself (i.e. it is used on
156 the CLASSPATH of users outside your own control), you should not use
157 experimental APIs, unless you repackage them (e.g. using ProGuard).
158
159* Deprecated non-experimental APIs will be removed two years after the release
160 in which they are first deprecated. You must fix your references before this
161 time. If you don't, any manner of breakage could result (you are not
162 guaranteed a compilation error).
163
164* Protobuf message interfaces/classes are designed to be subclassed by protobuf
165 generated code only. Do not subclass these message interfaces/classes
166 yourself. We may add new methods to the message interfaces/classes which will
167 break your own subclasses.
168
169* Don't use any method/class that is marked as "used by generated code only".
170 Such methods/classes are subject to change.
171
172* Protobuf LITE runtime APIs are not stable yet. They are subject to change even
173 in minor version releases.
174
175## Documentation
176
177The complete documentation for Protocol Buffers is available via the
178web at:
179
180 https://developers.google.com/protocol-buffers/
181