1# Protocol Buffers - Code Example
2
3This directory contains example code that uses Protocol Buffers to manage an
4address book. Two programs are provided for each supported language. The
5add_person example adds a new person to an address book, prompting the user to
6input the person's information. The list_people example lists people already in
7the address book. The examples use the exact same format in all three languages,
8so you can, for example, use add_person_java to create an address book and then
9use list_people_python to read it.
10
11These examples are part of the Protocol Buffers tutorial, located at:
12  https://developers.google.com/protocol-buffers/docs/tutorials
13
14## Build the example using bazel
15
16The example requires bazel 0.5.4 or newer to build. You can download/install
17the latest version of bazel from bazel's release page:
18
19    https://github.com/bazelbuild/bazel/releases
20
21Once you have bazel installed, simply run the following command in this examples
22directory to build the code:
23
24    $ bazel build :all
25
26Then you can run the built binary:
27
28    $ bazel-bin/add_person_cpp addressbook.data
29
30To use protobuf in your own bazel project, please follow instructions in the
31[BUILD](BUILD) file and [WORKSPACE](WORKSPACE) file.
32
33## Build the example using make
34
35You must install the protobuf package before you can build it using make. The
36minimum requirement is to install protocol compiler (i.e., the protoc binary)
37and the protobuf runtime for the language you want to build.
38
39You can simply run "make" to build the example for all languages (except for
40Go). However, since different language has different installation requirement,
41it will likely fail. It's better to follow individual instructions below to
42build only the language you are interested in.
43
44### C++
45
46You can follow instructions in [../src/README.md](../src/README.md) to install
47protoc and protobuf C++ runtime from source.
48
49Then run "make cpp" in this examples directory to build the C++ example. It
50will create two executables: add_person_cpp and list_people_cpp. These programs
51simply take an address book file as their parameter. The add_person_cpp
52programs will create the file if it doesn't already exist.
53
54To run the examples:
55
56    $ ./add_person_cpp addressbook.data
57    $ ./list_people_cpp addressbook.data
58
59Note that on some platforms you may have to edit the Makefile and remove
60"-lpthread" from the linker commands (perhaps replacing it with something else).
61We didn't do this automatically because we wanted to keep the example simple.
62
63### Python
64
65Follow instructions in [../README.md](../README.md) to install protoc and then
66follow [../python/README.md](../python/README.md) to install protobuf python
67runtime from source. You can also install python runtime using pip:
68
69    $ pip install protobuf
70
71Make sure the runtime version is the same as protoc binary, or it may not work.
72
73After you have install both protoc and python runtime, run "make python" to
74build two executables (shell scripts actually): add_person_python and
75list_people_python. They work the same way as the C++ executables.
76
77### Java
78
79Follow instructions in [../README.md](../README.md) to install protoc and then
80download protobuf Java runtime .jar file from maven:
81
82    https://mvnrepository.com/artifact/com.google.protobuf/protobuf-java
83
84Then run the following:
85
86    $ export CLASSPATH=/path/to/protobuf-java-[version].jar
87    $ make java
88
89This will create the add_person_java/list_people_java executables (shell
90scripts) and can be used to create/display an address book data file.
91
92### Go
93
94The Go example requires a plugin to the protocol buffer compiler, so it is not
95build with all the other examples.  See:
96
97    https://github.com/golang/protobuf
98
99for more information about Go protocol buffer support.
100
101First, install the Protocol Buffers compiler (protoc).
102
103Then, install the Go Protocol Buffers plugin ($GOPATH/bin must be in your $PATH
104for protoc to find it):
105
106    go get github.com/golang/protobuf/protoc-gen-go
107
108Build the Go samples in this directory with "make go".  This creates the
109following executable files in the current directory:
110
111    add_person_go      list_people_go
112
113To run the example:
114
115    ./add_person_go addressbook.data
116
117to add a person to the protocol buffer encoded file addressbook.data.  The file
118is created if it does not exist.  To view the data, run:
119
120    ./list_people_go addressbook.data
121
122Observe that the C++, Python, Java, and Dart examples in this directory run in a
123similar way and can view/modify files created by the Go example and vice
124versa.
125
126### Dart
127
128First, follow the instructions in [../README.md](../README.md) to install the Protocol Buffer Compiler (protoc).
129
130Then, install the Dart Protocol Buffer plugin as described [here](https://github.com/dart-lang/dart-protoc-plugin#how-to-build-and-use).
131Note, the executable `bin/protoc-gen-dart` must be in your `PATH` for `protoc` to find it.
132
133Build the Dart samples in this directory with `make dart`.
134
135To run the examples:
136
137```sh
138$ dart add_person.dart addessbook.data
139$ dart list_people.dart addressbook.data
140```
141
142The two programs take a protocol buffer encoded file as their parameter.
143The first can be used to add a person to the file. The file is created
144if it does not exist. The second displays the data in the file.
145