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