Protobuf is an implementation of Google's protocol buffers for Common Lisp.

The protobuf repository contains a compiler from .proto files to Lisp and
the run time support needed by the generated Lisp code.  Not all protocol
buffer features are implemented but the code works well enough that simple
serialization tests pass.

The protobuf code has been tested with ABCL, CCL, CLISP, and SBCL.  In the
past it has also worked with Allegro Common Lisp, but I have not tested it
recently.


INSTALLATION
============

0.  Install the software needed to clone a git repository and compile C++
code.  You'll need at least git, G++, and libtool, which on a Linux system
can often be installed with a package manager:

    apt-get install git g++ libtool


1. The Common Lisp protocol buffer compiler is implemented as a plugin to
Google's protocol buffer compiler, so you must first build and install
Google's compiler, which is called protoc.  The required code and
documentation are available here:

    http://code.google.com/p/protobuf/


2.  Clone the protobuf git repository to get a local copy.

    git clone git://github.com/brown/protobuf.git


3.  Compile protoc-gen-lisp, the Common Lisp protocol buffer plugin.
Currently, this step only works for Linux and is accomplished as follows:

    cd protobuf/protoc/lisp
    Manually edit INSTALL_ROOT and PROTOC_ROOT in Makefile.
    make install

Eventually, I will add GNU configure support and the compilation steps for
installing protoc-gen-lisp to /local/software/package/protoc-gen-lisp will
become:

    cd protobuf/protoc/lisp
    ./autogen.sh
    ./configure \
        --prefix=/local/software/package/protoc-gen-lisp \
        --with-protoc=/local/software/package/google-protobuf
    make install


4. Download and install the Common Lisp packages that protobuf depends on.
You'll need ASDF, but it comes pre-installed in most Common Lisp
distributions.  If you're not using Allegro, CLisp, or SBCL, you may need
trivial-utf8, which is available here:

    http://common-lisp.net/project/trivial-utf-8/

To run all the tests, you'll need the Stefil testing package and its
dependencies:

    hu.dwim.stefil
    hu.dwim.asdf
    alexandria


5. Make protobuf.asd available to ASDF.  There are several ways to do this
and you should consult the ASDF documentation to determine what will work
best for you.  ASDF and its manual are available here:

    http://common-lisp.net/project/asdf/


6. Tell ASDF where to find Google's protocol buffer compiler and the Common
Lisp plugin.  The file paths to use depend on where you have installed each.
You can either edit the pathnames used to initialize ASDF::*PROTOC* and
ASDF:*PROTOC-GEN-LISP* in protobuf.asd or you can set these variables in a
Lisp initialization file before protobuf.asd is loaded by ASDF.


7. Compile and load all the protobuf code:

    (asdf:load-system 'protobuf)


8. Optionally, load and run all the tests:

    (asdf:test-system 'varint)
    (asdf:test-system 'protobuf-test)


9. Compile and run the example code, which shows how to incorporate protocol
buffer definition files into your own projects:

    (asdf:load-system 'protobuf-example)

    (in-package address-book)
    (add-person :id 100
                :name "Robert Brown"
                :email-address "brown@foo.com"
                :phone-numbers '((home . "718-555-1212")
                                 (work . "212-589-1212")
                                 (mobile . "917-555-1212")))
    (list-people)


BUGS
====

Please report bugs and send suggestions to protobuf-devel@common-lisp.net or
contact me directly.  My email is robert.brown at the mail hosting site
gmail.com.