README.md
1Protocol Buffers - Google's data interchange format
2===================================================
3
4[](https://travis-ci.org/google/protobuf)
5
6Copyright 2008 Google Inc.
7
8This directory contains the Java Protocol Buffers runtime library.
9
10Installation - With Maven
11=========================
12
13The Protocol Buffers build is managed using Maven. If you would
14rather build without Maven, see below.
15
161) Install Apache Maven if you don't have it:
17
18 http://maven.apache.org/
19
202) 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
303) 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
374) Install the library into your Maven repository:
38
39 $ mvn install
40
415) 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
48The 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
60Installation - Without Maven
61============================
62
63If you would rather not install Maven to build the library, you may
64follow these instructions instead. Note that these instructions skip
65running unit tests and only describes how to install the core protobuf
66library (without the util package).
67
681) 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
772) Invoke protoc to build DescriptorProtos.java:
78
79 $ protoc --java_out=core/src/main/java -I../src \
80 ../src/google/protobuf/descriptor.proto
81
823) Compile the code in core/src/main/java using whatever means you prefer.
83
844) Install the classes wherever you prefer.
85
86Compatibility 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
121Documentation
122=============
123
124The complete documentation for Protocol Buffers is available via the
125web at:
126
127 https://developers.google.com/protocol-buffers/
128
){kind=link}