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