README.md 6.11 KB
Newer Older
1
# Protocol Buffers - Google's data interchange format
2

temporal's avatar
temporal committed
3 4
Copyright 2008 Google Inc.

5 6 7 8 9 10 11 12 13 14 15
https://developers.google.com/protocol-buffers/

## Use Java Protocol Buffers

To use protobuf in Java, first obtain the protocol compiler (a.k.a., protoc,
see instructions in the toplevel [README.md](../README.md)) and use it to
generate Java code for your .proto files:

    $ protoc --java_out=${OUTPUT_DIR} path/to/your/proto/file

Include the generated Java files in your project and add a dependency on the
16 17 18 19 20
protobuf Java runtime.

### Maven

If you are using Maven, use the following:
21 22 23 24 25

```xml
<dependency>
  <groupId>com.google.protobuf</groupId>
  <artifactId>protobuf-java</artifactId>
26
  <version>3.11.0</version>
27 28 29 30 31 32 33 34 35 36 37 38 39
</dependency>
```

Make sure the version number of the runtime matches (or is newer than) the
version number of the protoc.

If you want to use features like protobuf JsonFormat, add a dependency on the
protobuf-java-util package:

```xml
<dependency>
  <groupId>com.google.protobuf</groupId>
  <artifactId>protobuf-java-util</artifactId>
40
  <version>3.11.0</version>
41 42 43
</dependency>
```

44 45 46 47
### Gradle

If you are using Gradle, add the following to your `build.gradle` file's dependencies:
```
48
    compile 'com.google.protobuf:protobuf-java:3.11.0'
49 50 51
```
Again, be sure to check that the version number maches (or is newer than) the version number of protoc that you are using.

52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67
### Use Java Protocol Buffers on Android

For Android users, it's recommended to use protobuf Java Lite runtime because
of its smaller code size. Java Lite runtime also works better with Proguard
because it doesn't rely on Java reflection and is optimized to allow as much
code stripping as possible. You can following these [instructions to use Java
Lite runtime](lite.md).

### Use Java Protocol Buffers with Bazel

Bazel has native build rules to work with protobuf. For Java, you can use the
`java_proto_library` rule for server and the `java_lite_proto_library` rule
for Android. Check out [our build files examples](../examples/BUILD) to learn
how to use them.

## Build from Source
temporal's avatar
temporal committed
68

69 70 71 72
Most users should follow the instructions above to use protobuf Java runtime.
If you are contributing code to protobuf or want to use a protobuf version
that hasn't been officially released yet, you can folllow the instructions
below to build protobuf from source code.
temporal's avatar
temporal committed
73

74
### Build from Source - With Maven
temporal's avatar
temporal committed
75 76 77 78 79

1) Install Apache Maven if you don't have it:

     http://maven.apache.org/

80 81 82 83
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:
temporal's avatar
temporal committed
84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106

     $ protoc --version

   You will need to place the protoc executable in ../src.  (If you
   built it yourself, it should already be there.)

3) Run the tests:

     $ mvn test

   If some tests fail, this library may not work correctly on your
   system.  Continue at your own risk.

4) Install the library into your Maven repository:

     $ mvn install

5) If you do not use Maven to manage your own build, you can build a
   .jar file to use:

     $ mvn package

   The .jar will be placed in the "target" directory.
kenton@google.com's avatar
kenton@google.com committed
107

108
The above instructions will install 2 maven artifacts:
109

110 111 112 113 114
  * protobuf-java: The core Java Protocol Buffers library. Most users only
                   need this artifact.
  * protobuf-java-util: Utilities to work with protos. It contains JSON support
                        as well as utilities to work with proto3 well-known
                        types.
temporal's avatar
temporal committed
115

116
### Build from Source - Without Maven
temporal's avatar
temporal committed
117 118 119

If you would rather not install Maven to build the library, you may
follow these instructions instead.  Note that these instructions skip
120 121
running unit tests and only describes how to install the core protobuf
library (without the util package).
temporal's avatar
temporal committed
122 123 124 125 126 127 128 129 130 131 132 133

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
   version as this package.  If in doubt, run:

     $ protoc --version

   If you built the C++ code without installing, the compiler binary
   should be located in ../src.

2) Invoke protoc to build DescriptorProtos.java:

134
     $ protoc --java_out=core/src/main/java -I../src \
temporal's avatar
temporal committed
135 136
         ../src/google/protobuf/descriptor.proto

137
3) Compile the code in core/src/main/java using whatever means you prefer.
temporal's avatar
temporal committed
138 139 140

4) Install the classes wherever you prefer.

141
## Compatibility Notice
142 143 144

* Protobuf minor version releases are backwards-compatible. If your code
  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 147 148
  are guaranteed for minor version releases if the user follows the guideline
  described in this section.

Brian Wignall's avatar
Brian Wignall committed
149
* Protobuf major version releases may also be backwards-compatible with the
150 151 152 153 154
  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
155
  compatibility is needed. If your code is a library itself (i.e. it is used on
156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174
  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.

175
## Documentation
temporal's avatar
temporal committed
176 177 178 179

The complete documentation for Protocol Buffers is available via the
web at:

180
  https://developers.google.com/protocol-buffers/