README

   1 Go support for Protocol Buffers - Google's data interchange format
   2 Copyright 2010 Google Inc.
   3 http://code.google.com/p/goprotobuf/
   4
   5 This software implements Go bindings for protocol buffers.  For
   6 information about protocol buffers themselves, see
   7         http://code.google.com/apis/protocolbuffers/
   8 To use this software, you must first install the standard C++
   9 implementation of protocol buffers from
  10         http://code.google.com/p/protobuf/
  11 And of course you must also install the Go compiler and tools from
  12         http://code.google.com/p/go/
  13 See
  14         http://golang.org/doc/install.html
  15 for details or, if you are using gccgo, follow the instructions at
  16         http://golang.org/doc/gccgo_install.html
  17
  18 This software has two parts: a 'protocol compiler plugin' that
  19 generates Go source files that, once compiled, can access and manage
  20 protocol buffers; and a library that implements run-time support for
  21 encoding (marshaling), decoding (unmarshaling), and accessing protocol
  22 buffers.
  23
  24 There is no support for RPC in Go using protocol buffers.  It may come
  25 once a standard RPC protocol develops for protobufs.
  26
  27 There are no insertion points in the plugin.
  28
  29 To install this code:
  30
  31 The simplest way is to run goinstall.
  32
  33         # Grab the code from the repository and install the proto package.
  34         goinstall goprotobuf.googlecode.com/hg/proto
  35
  36         # Compile and install the compiler plugin
  37         cd $GOROOT/src/pkg/goprotobuf.googlecode.com/hg/compiler
  38         make install
  39
  40 The compiler plugin, protoc-gen-go, will be installed in $GOBIN,
  41 defaulting to $HOME/bin.  It must be in your $PATH for the protocol
  42 compiler, protoc, to find it.
  43
  44 Once the software is installed, there are two steps to using it.
  45 First you must compile the protocol buffer definitions and then import
  46 them, with the support library, into your program.
  47
  48 To compile the protocol buffer definition, write a Makefile in the
  49 style shown in the comment in the file Make.protobuf.  If your Makefile
  50 includes Make.protobuf, the rest should follow automatically.  The
  51 generated code can be compiled separately or as part of a normal Go
  52 package.
  53
  54 The generated files will be suffixed .pb.go.  See the Test code below
  55 for an example using such a file.
  56
  57 This repository uses the same code review mechanism as Go, so
  58 if you wish to submit changes add the equivalent of these two lines
  59 to $GOROOT/src/pkg/goprotobuf.googlecode.com/hg/.hg/hgrc
  60
  61         [extensions]
  62         codereview = $GOROOT/lib/codereview/codereview.py
  63
  64 *where $GOROOT is the expanded text, such as /usr/foo/go*.
  65
  66 The package comment for the proto library contains text describing
  67 the interface provided in Go for protocol buffers. Here is an edited
  68 version.
  69
  70 ==========
  71
  72 The proto package converts data structures to and from the
  73 wire format of protocol buffers.  It works in concert with the
  74 Go source code generated for .proto files by the protocol compiler.
  75
  76 A summary of the properties of the protocol buffer interface
  77 for a protocol buffer variable v:
  78
  79   - Names are turned from camel_case to CamelCase for export.
  80   - There are no methods on v to set and get fields; just treat
  81         them as structure fields.
  82   - The zero value for a struct is its correct initialization state.
  83         All desired fields must be set before marshaling.
  84   - A Reset() method will restore a protobuf struct to its zero state.
  85   - Non-repeated fields are pointers to the values; nil means unset.
  86         That is, optional or required field int32 f becomes F *int32.
  87   - Repeated fields are slices.
  88   - Helper functions are available to simplify the getting and setting of fields:
  89         foo.String = proto.String("hello") // set field
  90         s := proto.GetString(foo.String)  // get field
  91   - Constants are defined to hold the default values of all fields that
  92         have them.  They have the form Default_StructName_FieldName.
  93   - Enums are given type names and maps between names to values,
  94         plus a helper function to create values.  Enum values are prefixed
  95         with the enum's type name.
  96   - Nested groups and enums have type names prefixed with the name of
  97         the surrounding message type.
  98   - Marshal and Unmarshal are functions to encode and decode the wire format.
  99
 100 Consider file test.proto, containing
 101
 102         package example;
 103
 104         enum FOO { X = 17; };
 105
 106         message Test {
 107           required string label = 1;
 108           optional int32 type = 2 [default=77];
 109           repeated int64 reps = 3;
 110           optional group OptionalGroup = 4 {
 111             required string RequiredField = 5;
 112           };
 113         }
 114
 115 To build a package from test.proto and some other Go files, write a
 116 Makefile like this:
 117
 118         include $(GOROOT)/src/Make.$(GOARCH)
 119
 120         TARG=path/to/example
 121         GOFILES=\
 122                 test.pb.go\
 123                 other.go
 124
 125         include $(GOROOT)/src/Make.pkg
 126         include $(GOROOT)/src/pkg/goprotobuf.googlecode.com/hg/Make.protobuf
 127
 128
 129 To create and play with a Test object from the example package,
 130
 131         package main
 132
 133         import (
 134                 "log"
 135
 136                 "goprotobuf.googlecode.com/hg/proto"
 137                 "path/to/example"
 138         )
 139
 140         func main() {
 141                 test := &example.Test {
 142                         Label: proto.String("hello"),
 143                         Type: proto.Int32(17),
 144                         Optionalgroup: &example.Test_OptionalGroup {
 145                                 RequiredField: proto.String("good bye"),
 146                         },
 147                 }
 148                 data, err := proto.Marshal(test)
 149                 if err != nil {
 150                         log.Fatal("marshaling error: ", err)
 151                 }
 152                 newTest := &example.Test{}
 153                 err = proto.Unmarshal(data, newTest)
 154                 if err != nil {
 155                         log.Fatal("unmarshaling error: ", err)
 156                 }
 157                 // Now test and newTest contain the same data.
 158                 if proto.GetString(test.Label) != proto.GetString(newTest.Label) {
 159                         log.Fatalf("data mismatch %q != %q", proto.GetString(test.Label), proto.GetString(newTest.Label))
 160                 }
 161                 // etc.
 162         }