OLD | NEW |
1 Protocol Buffers - Google's data interchange format | 1 Protocol Buffers - Google's data interchange format |
2 =================================================== | 2 =================================================== |
3 | 3 |
4 [![Build Status](https://travis-ci.org/google/protobuf.svg?branch=master)](https
://travis-ci.org/google/protobuf) | 4 [![Build Status](https://travis-ci.org/google/protobuf.svg?branch=master)](https
://travis-ci.org/google/protobuf) |
5 | 5 |
6 Copyright 2008 Google Inc. | 6 Copyright 2008 Google Inc. |
7 | 7 |
8 This directory contains the Java Protocol Buffers runtime library. | 8 This directory contains the Java Protocol Buffers runtime library. |
9 | 9 |
10 Installation - With Maven | 10 Installation - With Maven |
11 ========================= | 11 ========================= |
12 | 12 |
13 The Protocol Buffers build is managed using Maven. If you would | 13 The Protocol Buffers build is managed using Maven. If you would |
14 rather build without Maven, see below. | 14 rather build without Maven, see below. |
15 | 15 |
16 1) Install Apache Maven if you don't have it: | 16 1) Install Apache Maven if you don't have it: |
17 | 17 |
18 http://maven.apache.org/ | 18 http://maven.apache.org/ |
19 | 19 |
20 2) Build the C++ code, or obtain a binary distribution of protoc. If | 20 2) Build the C++ code, or obtain a binary distribution of protoc (see |
21 you install a binary distribution, make sure that it is the same | 21 the toplevel [README.md](../README.md)). If you install a binary |
22 version as this package. If in doubt, run: | 22 distribution, make sure that it is the same version as this package. |
| 23 If in doubt, run: |
23 | 24 |
24 $ protoc --version | 25 $ protoc --version |
25 | 26 |
26 You will need to place the protoc executable in ../src. (If you | 27 You will need to place the protoc executable in ../src. (If you |
27 built it yourself, it should already be there.) | 28 built it yourself, it should already be there.) |
28 | 29 |
29 3) Run the tests: | 30 3) Run the tests: |
30 | 31 |
31 $ mvn test | 32 $ mvn test |
32 | 33 |
33 If some tests fail, this library may not work correctly on your | 34 If some tests fail, this library may not work correctly on your |
34 system. Continue at your own risk. | 35 system. Continue at your own risk. |
35 | 36 |
36 4) Install the library into your Maven repository: | 37 4) Install the library into your Maven repository: |
37 | 38 |
38 $ mvn install | 39 $ mvn install |
39 | 40 |
40 5) If you do not use Maven to manage your own build, you can build a | 41 5) If you do not use Maven to manage your own build, you can build a |
41 .jar file to use: | 42 .jar file to use: |
42 | 43 |
43 $ mvn package | 44 $ mvn package |
44 | 45 |
45 The .jar will be placed in the "target" directory. | 46 The .jar will be placed in the "target" directory. |
46 | 47 |
47 Installation - 'Lite' Version - With Maven | 48 The above instructions will install 3 maven artifacts: |
48 ========================================== | |
49 | 49 |
50 Building the 'lite' version of the Java Protocol Buffers library is | 50 * protobuf-java: The core Java Protocol Buffers library. Most users only |
51 the same as building the full version, except that all commands are | 51 need this artifact. |
52 run using the 'lite' profile. (see | 52 * protobuf-lite: The lite version of core Java Protobuf Buffers library. It |
53 http://maven.apache.org/guides/introduction/introduction-to-profiles.html) | 53 is a subset of the core library and is used together with |
54 | 54 the 'lite' code generator flag to reduce generated code size |
55 E.g. to install the lite version of the jar, you would run: | 55 for mobile. |
56 | 56 * protobuf-java-util: Utilities to work with protos. It contains JSON support |
57 $ mvn install -P lite | 57 as well as utilities to work with proto3 well-known |
58 | 58 types. |
59 The resulting artifact has the 'lite' classifier. To reference it | |
60 for dependency resolution, you would specify it as: | |
61 | |
62 ``` | |
63 <dependency> | |
64 <groupId>com.google.protobuf</groupId> | |
65 <artifactId>protobuf-java</artifactId> | |
66 <version>${version}</version> | |
67 <classifier>lite</classifier> | |
68 </dependency> | |
69 ``` | |
70 | 59 |
71 Installation - Without Maven | 60 Installation - Without Maven |
72 ============================ | 61 ============================ |
73 | 62 |
74 If you would rather not install Maven to build the library, you may | 63 If you would rather not install Maven to build the library, you may |
75 follow these instructions instead. Note that these instructions skip | 64 follow these instructions instead. Note that these instructions skip |
76 running unit tests. | 65 running unit tests and only describes how to install the core protobuf |
| 66 library (without the util package). |
77 | 67 |
78 1) Build the C++ code, or obtain a binary distribution of protoc. If | 68 1) Build the C++ code, or obtain a binary distribution of protoc. If |
79 you install a binary distribution, make sure that it is the same | 69 you install a binary distribution, make sure that it is the same |
80 version as this package. If in doubt, run: | 70 version as this package. If in doubt, run: |
81 | 71 |
82 $ protoc --version | 72 $ protoc --version |
83 | 73 |
84 If you built the C++ code without installing, the compiler binary | 74 If you built the C++ code without installing, the compiler binary |
85 should be located in ../src. | 75 should be located in ../src. |
86 | 76 |
87 2) Invoke protoc to build DescriptorProtos.java: | 77 2) Invoke protoc to build DescriptorProtos.java: |
88 | 78 |
89 $ protoc --java_out=src/main/java -I../src \ | 79 $ protoc --java_out=core/src/main/java -I../src \ |
90 ../src/google/protobuf/descriptor.proto | 80 ../src/google/protobuf/descriptor.proto |
91 | 81 |
92 3) Compile the code in src/main/java using whatever means you prefer. | 82 3) Compile the code in core/src/main/java using whatever means you prefer. |
93 | 83 |
94 4) Install the classes wherever you prefer. | 84 4) Install the classes wherever you prefer. |
95 | 85 |
96 Usage | 86 Compatibility Notice |
97 ===== | 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 ============= |
98 | 123 |
99 The complete documentation for Protocol Buffers is available via the | 124 The complete documentation for Protocol Buffers is available via the |
100 web at: | 125 web at: |
101 | 126 |
102 https://developers.google.com/protocol-buffers/ | 127 https://developers.google.com/protocol-buffers/ |
OLD | NEW |