Skip to content

Home

Jump to bottom Edit New page
Louis Thibault edited this page Dec 2, 2021 · 8 revisions

Quickstart

  • Start here to get started with:

    • Installation
    • Compiling schema files
    • Marshalling data
    • Remote Procedure Calls

  • The package documentation contains additional details about implementation.

News

28 October 2021: Following the recent merging of the v3 branch into main, the Getting Started Wiki page has been updated to reflect the new v3 syntax. We will be prioritizing development of version 3 and encourage all users to make the switch.

17 July 2016: New pogs package! You can now convert between Go structs and Cap'n Proto structs using reflection. From the release announcment:

If you're using go-capnproto2, there's a new subpackage: pogs (Plain Ol' Go Structs). It exposes two easy-to-use functions that convert Cap'n Proto structs to and from plain Go structs using reflection. This means that you can define structs that do narrow reads and writes, similar to the encoding/json package in Go's standard library.

This method of using go-capnproto2 is fully interoperable with existing code: under the hood, the pogs package uses the same logic for accessing and setting fields as the generated code, but it walks over the Cap'n Proto schema and the Go reflection API to map between the two. Obviously, this will be slower than accessing fields using the generated code since it uses reflection and copies memory. However, for less performance-sensitive code, this may be an acceptable tradeoff.

This feature is well unit-tested, but is relatively new code, so please file bugs as you find rough edges. To grab this package, run go get -u zombiezen.com/go/capnproto2/pogs and check out the docs on godoc.

25 March 2016: capnp.Pointer is deprecated; use capnp.Ptr. Details

20 September 2015: Based on this thread, I have changed the import path to zombiezen.com/go/capnproto2.

22 August 2015: API breakage time! Grep through the commit history for "API change" to see precise changes. The main impact on application code is that more functions that could fail previously and silently swallow errors now return them. Most of the methods on Struct or Pointer are now package functions to improve consistency with generated code.

On the flip side, I am now marking the API as stable, barring major changes to the Cap'n Proto specification. See the API stability section below.

16 August 2015: I'm cleaning up the API to make it more Go-like. This change will mostly affect those that were using the runtime library directly, but the generated code will now expose errors in places that it hasn't before. Watch the cleanup branch for changes, and expect the branch to be merged in the next few weeks.

Why the change? Since most users of the go-capnproto package are depending on Jason's (@glycerine) fork, I want to take the opportunity to clean up non-idiomatic parts of the API. In particular, the current design makes it difficult to implement new allocation algorithms or make changes to internals without breaking callers. The main goals are:

  • Surface errors from Message that were being silenced before.
  • Make all integer parameters use types (e.g. addresses can't be mixed with sizes, etc.).
  • Make Pointer into an interface instead of a struct. Pointer is already essentially a generic type, but its fields are not well documented and confusing. By making the generated code embed exactly the pointer type they need, this should reduce memory usage and provide more type checking.

6 August 2015: Level 1 RPC support with some known issues. I've added a section about compatibility guarantees below. -Ross

23 July 2015: Level 0 RPC support (and parts of Level 1)!

The rest of Level 1 will be coming soon. -Ross

19 February 2015: This is a fork of Jason Aten's go-capnproto branch that supports Cap'n Proto interfaces. It's not API compatible, as I chose to clean up some of the naming rules to bring it more in line with the Protobuf code generator. Jason has agreed that this should live as its own fork for a while, but I will try to upstream as much as possible. As a result, some branches in this repo may be used to push smaller features back upstream. -Ross

5 April 2014: James McKaskill, the author of go-capnproto (https://github.com/jmckaskill/go-capnproto), has been super busy of late, so I agreed to take over as maintainer. This branch (https://github.com/glycerine/go-capnproto) includes my recent work to fix bugs in the creation (originating) of structs for Go, and an implementation of the packing/unpacking capnp specification. Thanks to Albert Strasheim (https://github.com/alberts/go-capnproto) of CloudFlare for a great set of packing tests. - Jason

Add a custom footer
Add a custom sidebar
Clone this wiki locally