cannam@48: ---
cannam@48: layout: page
cannam@48: title: Other Languages
cannam@48: ---
cannam@48: 
cannam@48: # Other Languages
cannam@48: 
cannam@48: Cap'n Proto's reference implementation is in C++.  Implementations in other languages are
cannam@48: maintained by respective authors and have not been reviewed by me
cannam@48: ([@kentonv](https://github.com/kentonv)). Below are the implementations I'm aware
cannam@48: of. Some of these projects are more "ready" than others; please consult each
cannam@48: project's documentation for details.
cannam@48: 
cannam@48: ##### Serialization + RPC
cannam@48: 
cannam@48: * [C++](cxx.html) by [@kentonv](https://github.com/kentonv)
cannam@48: * [Erlang](http://ecapnp.astekk.se/) by [@kaos](https://github.com/kaos)
cannam@48: * [Go](https://github.com/zombiezen/go-capnproto2) by [@zombiezen](https://github.com/zombiezen) (forked from [@glycerine](https://github.com/glycerine)'s serialization-only version, below)
cannam@48: * [Javascript (Node.js only)](https://github.com/kentonv/node-capnp) by [@kentonv](https://github.com/kentonv)
cannam@48: * [Python](http://jparyani.github.io/pycapnp/) by [@jparyani](https://github.com/jparyani)
cannam@48: * [Rust](https://github.com/dwrensha/capnproto-rust) by [@dwrensha](https://github.com/dwrensha)
cannam@48: 
cannam@48: ##### Serialization only
cannam@48: 
cannam@48: * [C](https://github.com/opensourcerouting/c-capnproto) by [OpenSourceRouting](https://www.opensourcerouting.org/) / [@eqvinox](https://github.com/eqvinox) (originally by [@jmckaskill](https://github.com/jmckaskill))
cannam@48: * [C#](https://github.com/mgravell/capnproto-net) by [@mgravell](https://github.com/mgravell)
cannam@48: * [Go](https://github.com/glycerine/go-capnproto) by [@glycerine](https://github.com/glycerine) (originally by [@jmckaskill](https://github.com/jmckaskill))
cannam@48: * [Java](https://github.com/dwrensha/capnproto-java/) by [@dwrensha](https://github.com/dwrensha)
cannam@48: * [Javascript](https://github.com/popham/capnp-js-base) by [@popham](https://github.com/popham)
cannam@48: * [Javascript](https://github.com/jscheid/capnproto-js) (older, abandoned) by [@jscheid](https://github.com/jscheid)
cannam@48: * [Lua](https://github.com/cloudflare/lua-capnproto) by [CloudFlare](http://www.cloudflare.com/) / [@calio](https://github.com/calio)
cannam@48: * [Nim](https://github.com/zielmicha/capnp.nim) by [@zielmicha](https://github.com/zielmicha)
cannam@48: * [OCaml](https://github.com/pelzlpj/capnp-ocaml) by [@pelzlpj](https://github.com/pelzlpj)
cannam@48: * [Ruby](https://github.com/cstrahan/capnp-ruby) by [@cstrahan](https://github.com/cstrahan)
cannam@48: 
cannam@48: ##### Tools
cannam@48: 
cannam@48: These are other misc projects related to Cap'n Proto that are not actually implementations in
cannam@48: new languages.
cannam@48: 
cannam@48: * [Common Test Framework](https://github.com/kaos/capnp_test) by [@kaos](https://github.com/kaos)
cannam@48: * [Sublime Syntax Highlighting](https://github.com/joshuawarner32/capnproto-sublime) by
cannam@48:   [@joshuawarner32](https://github.com/joshuawarner32)
cannam@48: * [Vim Syntax Highlighting](https://github.com/peter-edge/vim-capnp) by [@peter-edge](https://github.com/peter-edge)
cannam@48:   (originally by [@cstrahan](https://github.com/cstrahan))
cannam@48: * [Wireshark Dissector Plugin](https://github.com/kaos/wireshark-plugins) by [@kaos](https://github.com/kaos)
cannam@48: 
cannam@48: ## Contribute Your Own!
cannam@48: 
cannam@48: We'd like to support many more languages in the future!
cannam@48: 
cannam@48: If you'd like to own the implementation of Cap'n Proto in some particular language,
cannam@48: [let us know](https://groups.google.com/group/capnproto)!
cannam@48: 
cannam@48: **You should e-mail the list _before_ you start hacking.**  We don't bite, and we'll probably have
cannam@48: useful tips that will save you time.  :)
cannam@48: 
cannam@48: **Do not implement your own schema parser.**  The schema language is more complicated than it
cannam@48: looks, and the algorithm to determine offsets of fields is subtle.  If you reuse the official
cannam@48: parser, you won't risk getting these wrong, and you won't have to spend time keeping your parser
cannam@48: up-to-date.  In fact, you can still write your code generator in any language you want, using
cannam@48: compiler plugins!
cannam@48: 
cannam@48: ### How to Write Compiler Plugins
cannam@48: 
cannam@48: The Cap'n Proto tool, `capnp`, does not actually know how to generate code.  It only parses schemas,
cannam@48: then hands the parse tree off to another binary -- known as a "plugin" -- which generates the code.
cannam@48: Plugins are independent executables (written in any language) which read a description of the
cannam@48: schema from standard input and then generate the necessary code.  The description is itself a
cannam@48: Cap'n Proto message, defined by
cannam@48: [schema.capnp](https://github.com/sandstorm-io/capnproto/blob/master/c%2B%2B/src/capnp/schema.capnp).
cannam@48: Specifically, the plugin receives a `CodeGeneratorRequest`, using
cannam@48: [standard serialization](encoding.html#serialization-over-a-stream)
cannam@48: (not packed).  (Note that installing the C++ runtime causes schema.capnp to be placed in
cannam@48: `$PREFIX/include/capnp` -- `/usr/local/include/capnp` by default).
cannam@48: 
cannam@48: Of course, because the input to a plugin is itself in Cap'n Proto format, if you write your
cannam@48: plugin directly in the language you wish to support, you may have a bootstrapping problem:  you
cannam@48: somehow need to generate code for `schema.capnp` before you write your code generator.  Luckily,
cannam@48: because of the simplicity of the Cap'n Proto format, it is generally not too hard to do this by
cannam@48: hand.  Remember that you can use `capnp compile -ocapnp schema.capnp` to get a dump of the sizes
cannam@48: and offsets of all structs and fields defined in the file.
cannam@48: 
cannam@48: `capnp compile` normally looks for plugins in `$PATH` with the name `capnpc-[language]`, e.g.
cannam@48: `capnpc-c++` or `capnpc-capnp`.  However, if the language name given on the command line contains
cannam@48: a slash character, `capnp` assumes that it is an exact path to the plugin executable, and does not
cannam@48: search `$PATH`.  Examples:
cannam@48: 
cannam@48:     # Searches $PATH for executable "capnpc-mylang".
cannam@48:     capnp compile -o mylang addressbook.capnp
cannam@48: 
cannam@48:     # Uses plugin executable "myplugin" from the current directory.
cannam@48:     capnp compile -o ./myplugin addressbook.capnp
cannam@48: 
cannam@48: If the user specifies an output directory, the compiler will run the plugin with that directory
cannam@48: as the working directory, so you do not need to worry about this.
cannam@48: 
cannam@48: For examples of plugins, take a look at
cannam@48: [capnpc-capnp](https://github.com/sandstorm-io/capnproto/blob/master/c%2B%2B/src/capnp/compiler/capnpc-capnp.c%2B%2B)
cannam@48: or [capnpc-c++](https://github.com/sandstorm-io/capnproto/blob/master/c%2B%2B/src/capnp/compiler/capnpc-c%2B%2B.c%2B%2B).
cannam@48: 
cannam@48: ### Supporting Dynamic Languages
cannam@48: 
cannam@48: Dynamic languages have no compile step.  This makes it difficult to work `capnp compile` into the
cannam@48: workflow for such languages.  Additionally, dynamic languages are often scripting languages that do
cannam@48: not support pointer arithmetic or any reasonably-performant alternative.
cannam@48: 
cannam@48: Fortunately, dynamic languages usually have facilities for calling native code.  The best way to
cannam@48: support Cap'n Proto in a dynamic language, then, is to wrap the C++ library, in particular the
cannam@48: [C++ dynamic API](cxx.html#dynamic-reflection).  This way you get reasonable performance while
cannam@48: still avoiding the need to generate any code specific to each schema.
cannam@48: 
cannam@48: To parse the schema files, use the `capnp::SchemaParser` class (defined in `capnp/schema-parser.h`).
cannam@48: This way, schemas are loaded at the same time as all the rest of the program's code -- at startup.
cannam@48: An advanced implementation might consider caching the compiled schemas in binary format, then
cannam@48: loading the cached version using `capnp::SchemaLoader`, similar to the way e.g. Python caches
cannam@48: compiled source files as `.pyc` bytecode, but that's up to you.
cannam@48: 
cannam@48: ### Testing Your Implementation
cannam@48: 
cannam@48: The easiest way to test that you've implemented the spec correctly is to use the `capnp` tool
cannam@48: to [encode](capnp-tool.html#encoding-messages) test inputs and
cannam@48: [decode](capnp-tool.html#decoding-messages) outputs.