diff options
| -rw-r--r-- | README.md | 14 | ||||
| -rw-r--r-- | examples/BUILD | 101 | ||||
| -rw-r--r-- | examples/ListPeople.java | 3 | ||||
| -rw-r--r-- | examples/Makefile | 2 | ||||
| -rw-r--r-- | examples/README.md | 124 | ||||
| -rw-r--r-- | examples/README.txt | 61 | ||||
| -rw-r--r-- | examples/WORKSPACE | 33 | ||||
| -rw-r--r-- | examples/add_person.cc | 9 | ||||
| -rw-r--r-- | examples/addressbook.proto | 4 | ||||
| -rw-r--r-- | examples/list_people.cc | 13 |
10 files changed, 298 insertions, 66 deletions
@@ -68,9 +68,19 @@ how to install protobuf runtime for that specific language: | PHP | [php](php) | | Dart | [dart-lang/protobuf](https://github.com/dart-lang/protobuf) | +Quick Start +----------- -Usage ------ +The best way to learn how to use protobuf is to follow the tutorials in our +developer guide: + +https://developers.google.com/protocol-buffers/docs/tutorials + +If you want to learn from code examples, take a look at the examples in the +[examples](examples) directory. + +Documentation +------------- The complete documentation for Protocol Buffers is available via the web at: diff --git a/examples/BUILD b/examples/BUILD new file mode 100644 index 00000000..d5d5d9a5 --- /dev/null +++ b/examples/BUILD @@ -0,0 +1,101 @@ +# This BUILD file shows how to use protobuf with bazel. Before you can use +# proto_library/<lang>_proto_library rules in a BUILD file, you need to +# include protobuf repo as remote repositories in your WORKSPACE file. See +# the WORKSPACE file in the same directory with this BUILD file for an +# example. + +# For each .proto file, a proto_library target should be defined. This target +# is not bound to any particular language. Instead, it defines the dependency +# graph of the .proto files (i.e., proto imports) and serves as the provider +# of .proto source files to the protocol compiler. +# +# Remote repository "com_google_protobuf" must be defined to use this rule. +proto_library( + name = "addressbook_proto", + srcs = ["addressbook.proto"], + deps = ["@com_google_protobuf//:timestamp_proto"], +) + +# The cc_proto_library rule generates C++ code for a proto_library rule. It +# must have exactly one proto_library dependency. If you want to use multiple +# proto_library targets, create a separate cc_proto_library target for each +# of them. +# +# Remote repository "com_google_protobuf_cc" must be defined to use this rule. +cc_proto_library( + name = "addressbook_cc_proto", + deps = [":addressbook_proto"], +) + +# cc_library/cc_binary targets can depend on cc_proto_library targets. +cc_binary( + name = "add_person_cpp", + srcs = ["add_person.cc"], + deps = [":addressbook_cc_proto"], +) + +cc_binary( + name = "list_people_cpp", + srcs = ["list_people.cc"], + deps = [":addressbook_cc_proto"], +) + +# Similar to cc_proto_library but for Java. +# +# Remote repository "com_google_protobuf_java" must be defined to use this rule. +java_proto_library( + name = "addressbook_java_proto", + deps = [":addressbook_proto"], +) + +java_binary( + name = "add_person_java", + srcs = ["AddPerson.java"], + main_class = "AddPerson", + deps = [":addressbook_java_proto"], +) + +java_binary( + name = "list_people_java", + srcs = ["ListPeople.java"], + main_class = "ListPeople", + deps = [":addressbook_java_proto"], +) + +# Java lite. +# +# Remote repository "com_google_protobuf_javalite" must be defined to use this +# rule. +java_lite_proto_library( + name = "addressbook_java_lite_proto", + deps = [":addressbook_proto"], +) + +# Java lite API is a subset of the regular Java API so if you only uses this +# subset in your code, you can actually compile your code against both (i.e., +# share code between server build and Android build). +# +# The lite version has a smaller code size, and you can see that by comparing +# the resulted .jar file: +# +# $ bazel build :add_person_java_deploy.jar :add_person_java_lite_deploy.jar +# $ ls -l bazel-bin/*_deploy.jar +# -r-xr-xr-x 1 xiaofeng eng 1230797 Sep 8 12:24 bazel-bin/add_person_java_deploy.jar +# -r-xr-xr-x 1 xiaofeng eng 236166 Sep 8 12:24 bazel-bin/add_person_java_lite_deploy.jar +# +# In the above example, the lite .jar file is 6 times smaller. With proper +# proguard inlining/stripping, the difference can be much more larger than +# that. +java_binary( + name = "add_person_java_lite", + srcs = ["AddPerson.java"], + main_class = "AddPerson", + deps = [":addressbook_java_lite_proto"], +) + +java_binary( + name = "list_people_java_lite", + srcs = ["ListPeople.java"], + main_class = "ListPeople", + deps = [":addressbook_java_lite_proto"], +) diff --git a/examples/ListPeople.java b/examples/ListPeople.java index 78924305..580f7ac2 100644 --- a/examples/ListPeople.java +++ b/examples/ListPeople.java @@ -27,6 +27,9 @@ class ListPeople { case WORK: System.out.print(" Work phone #: "); break; + default: + System.out.println(" Unknown phone #: "); + break; } System.out.println(phoneNumber.getNumber()); } diff --git a/examples/Makefile b/examples/Makefile index d16bb56d..3b61790b 100644 --- a/examples/Makefile +++ b/examples/Makefile @@ -51,7 +51,7 @@ list_people_gotest: list_people.go list_people_go go test list_people.go list_people_test.go javac_middleman: AddPerson.java ListPeople.java protoc_middleman - javac -cp ../java/core/target/*.jar AddPerson.java ListPeople.java com/example/tutorial/AddressBookProtos.java + javac -cp $$CLASSPATH AddPerson.java ListPeople.java com/example/tutorial/AddressBookProtos.java @touch javac_middleman add_person_java: javac_middleman diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 00000000..20f285cd --- /dev/null +++ b/examples/README.md @@ -0,0 +1,124 @@ +# Protocol Buffers - Code Example + +This directory contains example code that uses Protocol Buffers to manage an +address book. Two programs are provided for each supported language. The +add_person example adds a new person to an address book, prompting the user to +input the person's information. The list_people example lists people already in +the address book. The examples use the exact same format in all three languages, +so you can, for example, use add_person_java to create an address book and then +use list_people_python to read it. + +These examples are part of the Protocol Buffers tutorial, located at: + https://developers.google.com/protocol-buffers/docs/tutorials + +## Build the example using bazel + +The example requires bazel 0.5.4 or newer to build. You can download/install +the latest version of bazel from bazel's release page: + + https://github.com/bazelbuild/bazel/releases + +Once you have bazel installed, simply run the following command in this examples +directory to build the code: + + $ bazel build :all + +Then you can run the built binary: + + $ bazel-bin/add_person_cpp addressbook.data + +To use protobuf in your own bazel project, please follow instructions in the +[BUILD](BUILD) file and [WORKSPACE](WORKSPACE) file. + +## Build the example using make + +You must install the protobuf package before you can build it using make. The +minimum requirement is to install protocol compiler (i.e., the protoc binary) +and the protobuf runtime for the language you want to build. + +You can simply run "make" to build the example for all languages (except for +Go). However, since different language has different installation requirement, +it will likely fail. It's better to follow individual instrutions below to +build only the language you are interested in. + +### C++ + +You can follow instructions in [../src/README.md](../src/README.md) to install +protoc and protobuf C++ runtime from source. + +Then run "make cpp" in this examples directory to build the C++ example. It +will create two executables: add_person_cpp and list_people_cpp. These programs +simply take an address book file as their parameter. The add_person_cpp +programs will create the file if it doesn't already exist. + +To run the examples: + + $ ./add_person_cpp addressbook.data + $ ./list_people_cpp addressbook.data + +Note that on some platforms you may have to edit the Makefile and remove +"-lpthread" from the linker commands (perhaps replacing it with something else). +We didn't do this automatically because we wanted to keep the example simple. + +### Python + +Follow instructions in [../README.md](../README.md) to install protoc and then +follow [../python/README.md](../python/README.md) to install protobuf python +runtime from source. You can also install python runtime using pip: + + $ pip install protobuf + +Make sure the runtime version is the same as protoc binary, or it may not work. + +After you have install both protoc and python runtime, run "make python" to +build two executables (shell scripts actually): add_person_python and +list_people_python. They work the same way as the C++ executables. + +### Java + +Follow instructions in [../README.md](../README.md) to install protoc and then +download protobuf Java runtime .jar file from maven: + + https://mvnrepository.com/artifact/com.google.protobuf/protobuf-java + +Then run the following: + + $ export CLASSPATH=/path/to/protobuf-java-[version].jar + $ make java + +This will create the add_person_java/list_people_java executables (shell +scripts) and can be used to create/display an address book data file. + +### Go + +The Go example requires a plugin to the protocol buffer compiler, so it is not +build with all the other examples. See: + + https://github.com/golang/protobuf + +for more information about Go protocol buffer support. + +First, install the Protocol Buffers compiler (protoc). + +Then, install the Go Protocol Buffers plugin ($GOPATH/bin must be in your $PATH +for protoc to find it): + + go get github.com/golang/protobuf/protoc-gen-go + +Build the Go samples in this directory with "make go". This creates the +following executable files in the current directory: + + add_person_go list_people_go + +To run the example: + + ./add_person_go addressbook.data + +to add a person to the protocol buffer encoded file addressbook.data. The file +is created if it does not exist. To view the data, run: + + ./list_people_go addressbook.data + +Observe that the C++, Python, and Java examples in this directory run in a +similar way and can view/modify files created by the Go example and vice +versa. diff --git a/examples/README.txt b/examples/README.txt deleted file mode 100644 index 2e4f6e4e..00000000 --- a/examples/README.txt +++ /dev/null @@ -1,61 +0,0 @@ -This directory contains example code that uses Protocol Buffers to manage an -address book. Two programs are provided, each with three different -implementations, one written in each of C++, Java, and Python. The add_person -example adds a new person to an address book, prompting the user to input -the person's information. The list_people example lists people already in the -address book. The examples use the exact same format in all three languages, -so you can, for example, use add_person_java to create an address book and then -use list_people_python to read it. - -You must install the protobuf package before you can build these. - -To build all the examples (on a unix-like system), simply run "make". This -creates the following executable files in the current directory: - add_person_cpp list_people_cpp - add_person_java list_people_java - add_person_python list_people_python - -If you only want to compile examples in one language, use "make cpp"*, -"make java", or "make python". - -All of these programs simply take an address book file as their parameter. -The add_person programs will create the file if it doesn't already exist. - -These examples are part of the Protocol Buffers tutorial, located at: - https://developers.google.com/protocol-buffers/docs/tutorials - -* Note that on some platforms you may have to edit the Makefile and remove -"-lpthread" from the linker commands (perhaps replacing it with something else). -We didn't do this automatically because we wanted to keep the example simple. - -## Java ## - -protobuf-java-*.jar can be generated by: - cd ../java - mvn package -and will be used by "make java" - -## Go ## - -The Go example requires a plugin to the protocol buffer compiler, so it is not -build with all the other examples. See: - https://github.com/golang/protobuf -for more information about Go protocol buffer support. - -First, install the Protocol Buffers compiler (protoc). -Then, install the Go Protocol Buffers plugin -($GOPATH/bin must be in your $PATH for protoc to find it): - go get github.com/golang/protobuf/protoc-gen-go - -Build the Go samples in this directory with "make go". This creates the -following executable files in the current directory: - add_person_go list_people_go -To run the example: - ./add_person_go addressbook.data -to add a person to the protocol buffer encoded file addressbook.data. The file -is created if it does not exist. To view the data, run: - ./list_people_go addressbook.data - -Observe that the C++, Python, and Java examples in this directory run in a -similar way and can view/modify files created by the Go example and vice -versa. diff --git a/examples/WORKSPACE b/examples/WORKSPACE new file mode 100644 index 00000000..bb003107 --- /dev/null +++ b/examples/WORKSPACE @@ -0,0 +1,33 @@ +# This com_google_protobuf repository is required for proto_library rule. +# It provides the protocol compiler binary (i.e., protoc). +http_archive( + name = "com_google_protobuf", + strip_prefix = "protobuf-master", + urls = ["https://github.com/google/protobuf/archive/master.zip"], +) + +# This com_google_protobuf_cc repository is required for cc_proto_library +# rule. It provides protobuf C++ runtime. Note that it actually is the same +# repo as com_google_protobuf but has to be given a different name as +# required by bazel. +http_archive( + name = "com_google_protobuf_cc", + strip_prefix = "protobuf-master", + urls = ["https://github.com/google/protobuf/archive/master.zip"], +) + +# Similar to com_google_protobuf_cc but for Java (i.e., java_proto_library). +http_archive( + name = "com_google_protobuf_java", + strip_prefix = "protobuf-master", + urls = ["https://github.com/google/protobuf/archive/master.zip"], +) + +# Similar to com_google_protobuf_cc but for Java lite. If you are building +# for Android, the lite version should be prefered because it has a much +# smaller code size. +http_archive( + name = "com_google_protobuf_javalite", + strip_prefix = "protobuf-javalite", + urls = ["https://github.com/google/protobuf/archive/javalite.zip"], +) diff --git a/examples/add_person.cc b/examples/add_person.cc index 9bec4b37..856e90bb 100644 --- a/examples/add_person.cc +++ b/examples/add_person.cc @@ -1,11 +1,17 @@ // See README.txt for information and build instructions. -#include <iostream> +#include <ctime> #include <fstream> +#include <google/protobuf/util/time_util.h> +#include <iostream> #include <string> + #include "addressbook.pb.h" + using namespace std; +using google::protobuf::util::TimeUtil; + // This function fills in a Person message based on user input. void PromptForAddress(tutorial::Person* person) { cout << "Enter person ID number: "; @@ -48,6 +54,7 @@ void PromptForAddress(tutorial::Person* person) { cout << "Unknown phone type. Using default." << endl; } } + *person->mutable_last_updated() = TimeUtil::SecondsToTimestamp(time(NULL)); } // Main function: Reads the entire address book from a file, diff --git a/examples/addressbook.proto b/examples/addressbook.proto index 23cc2f97..b4b33b4c 100644 --- a/examples/addressbook.proto +++ b/examples/addressbook.proto @@ -9,6 +9,8 @@ // [START declaration] syntax = "proto3"; package tutorial; + +import "google/protobuf/timestamp.proto"; // [END declaration] // [START java_declaration] @@ -38,6 +40,8 @@ message Person { } repeated PhoneNumber phones = 4; + + google.protobuf.Timestamp last_updated = 5; } // Our address book file is just one of these. diff --git a/examples/list_people.cc b/examples/list_people.cc index 68e5666d..b309c596 100644 --- a/examples/list_people.cc +++ b/examples/list_people.cc @@ -1,11 +1,16 @@ // See README.txt for information and build instructions. -#include <iostream> #include <fstream> +#include <google/protobuf/util/time_util.h> +#include <iostream> #include <string> + #include "addressbook.pb.h" + using namespace std; +using google::protobuf::util::TimeUtil; + // Iterates though all people in the AddressBook and prints info about them. void ListPeople(const tutorial::AddressBook& address_book) { for (int i = 0; i < address_book.people_size(); i++) { @@ -30,9 +35,15 @@ void ListPeople(const tutorial::AddressBook& address_book) { case tutorial::Person::WORK: cout << " Work phone #: "; break; + default: + cout << " Unknown phone #: "; + break; } cout << phone_number.number() << endl; } + if (person.has_last_updated()) { + cout << " Updated: " << TimeUtil::ToString(person.last_updated()) << endl; + } } } |