otherlang.md (8020B)
1 --- 2 layout: page 3 title: Other Languages 4 --- 5 6 # Other Languages 7 8 Cap'n Proto's reference implementation is in C++. Implementations in other languages are 9 maintained by respective authors and have not been reviewed by me 10 ([@kentonv](https://github.com/kentonv)). Below are the implementations I'm aware 11 of. Some of these projects are more "ready" than others; please consult each 12 project's documentation for details. 13 14 ##### Serialization + RPC 15 16 * [C++](cxx.html) by [@kentonv](https://github.com/kentonv) 17 * [C# (.NET Core)](https://github.com/c80k/capnproto-dotnetcore) by [@c80k](https://github.com/c80k) 18 * [Erlang](http://ecapnp.astekk.se/) by [@kaos](https://github.com/kaos) 19 * [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) 20 * [Haskell](https://github.com/zenhack/haskell-capnp) by [@zenhack](https://github.com/zenhack) 21 * [JavaScript (Node.js only)](https://github.com/capnproto/node-capnp) by [@kentonv](https://github.com/kentonv) 22 * [OCaml](https://github.com/capnproto/capnp-ocaml) by [@pelzlpj](https://github.com/pelzlpj) with [RPC](https://github.com/mirage/capnp-rpc) by [@talex5](https://github.com/talex5) 23 * [Python](http://capnproto.github.io/pycapnp/) by [@jparyani](https://github.com/jparyani) 24 * [Rust](https://github.com/dwrensha/capnproto-rust) by [@dwrensha](https://github.com/dwrensha) 25 26 ##### Serialization only 27 28 * [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)) 29 * [D](https://github.com/capnproto/capnproto-dlang) by [@ThomasBrixLarsen](https://github.com/ThomasBrixLarsen) 30 * [Go](https://github.com/glycerine/go-capnproto) by [@glycerine](https://github.com/glycerine) (originally by [@jmckaskill](https://github.com/jmckaskill)) 31 * [Java](https://github.com/capnproto/capnproto-java/) by [@dwrensha](https://github.com/dwrensha) 32 * [JavaScript](https://github.com/capnp-js/plugin/) by [@popham](https://github.com/popham) 33 * [JavaScript](https://github.com/jscheid/capnproto-js) (older, abandoned) by [@jscheid](https://github.com/jscheid) 34 * [Lua](https://github.com/cloudflare/lua-capnproto) by [CloudFlare](http://www.cloudflare.com/) / [@calio](https://github.com/calio) 35 * [Nim](https://github.com/zielmicha/capnp.nim) by [@zielmicha](https://github.com/zielmicha) 36 * [Ruby](https://github.com/cstrahan/capnp-ruby) by [@cstrahan](https://github.com/cstrahan) 37 * [Scala](https://github.com/katis/capnp-scala) by [@katis](https://github.com/katis) 38 39 ##### Tools 40 41 These are other misc projects related to Cap'n Proto that are not actually implementations in 42 new languages. 43 44 * [Common Test Framework](https://github.com/kaos/capnp_test) by [@kaos](https://github.com/kaos) 45 * [Sublime Syntax Highlighting](https://github.com/joshuawarner32/capnproto-sublime) by 46 [@joshuawarner32](https://github.com/joshuawarner32) 47 * [Vim Syntax Highlighting](https://github.com/cstrahan/vim-capnp) by [@cstrahan](https://github.com/cstrahan) 48 * [Wireshark Dissector Plugin](https://github.com/kaos/wireshark-plugins) by [@kaos](https://github.com/kaos) 49 * [VS Code Syntax Highlighter](https://marketplace.visualstudio.com/items?itemName=xmonader.vscode-capnp) by [@xmonader](https://github.com/xmonader) 50 * [IntelliJ Syntax Highlighter](https://github.com/xmonader/sercapnp) by [@xmonader](https://github.com/xmonader) 51 52 ## Contribute Your Own! 53 54 We'd like to support many more languages in the future! 55 56 If you'd like to own the implementation of Cap'n Proto in some particular language, 57 [let us know](https://groups.google.com/group/capnproto)! 58 59 **You should e-mail the list _before_ you start hacking.** We don't bite, and we'll probably have 60 useful tips that will save you time. :) 61 62 **Do not implement your own schema parser.** The schema language is more complicated than it 63 looks, and the algorithm to determine offsets of fields is subtle. If you reuse the official 64 parser, you won't risk getting these wrong, and you won't have to spend time keeping your parser 65 up-to-date. In fact, you can still write your code generator in any language you want, using 66 compiler plugins! 67 68 ### How to Write Compiler Plugins 69 70 The Cap'n Proto tool, `capnp`, does not actually know how to generate code. It only parses schemas, 71 then hands the parse tree off to another binary -- known as a "plugin" -- which generates the code. 72 Plugins are independent executables (written in any language) which read a description of the 73 schema from standard input and then generate the necessary code. The description is itself a 74 Cap'n Proto message, defined by 75 [schema.capnp](https://github.com/sandstorm-io/capnproto/blob/master/c%2B%2B/src/capnp/schema.capnp). 76 Specifically, the plugin receives a `CodeGeneratorRequest`, using 77 [standard serialization](encoding.html#serialization-over-a-stream) 78 (not packed). (Note that installing the C++ runtime causes schema.capnp to be placed in 79 `$PREFIX/include/capnp` -- `/usr/local/include/capnp` by default). 80 81 Of course, because the input to a plugin is itself in Cap'n Proto format, if you write your 82 plugin directly in the language you wish to support, you may have a bootstrapping problem: you 83 somehow need to generate code for `schema.capnp` before you write your code generator. Luckily, 84 because of the simplicity of the Cap'n Proto format, it is generally not too hard to do this by 85 hand. Remember that you can use `capnp compile -ocapnp schema.capnp` to get a dump of the sizes 86 and offsets of all structs and fields defined in the file. 87 88 `capnp compile` normally looks for plugins in `$PATH` with the name `capnpc-[language]`, e.g. 89 `capnpc-c++` or `capnpc-capnp`. However, if the language name given on the command line contains 90 a slash character, `capnp` assumes that it is an exact path to the plugin executable, and does not 91 search `$PATH`. Examples: 92 93 # Searches $PATH for executable "capnpc-mylang". 94 capnp compile -o mylang addressbook.capnp 95 96 # Uses plugin executable "myplugin" from the current directory. 97 capnp compile -o ./myplugin addressbook.capnp 98 99 If the user specifies an output directory, the compiler will run the plugin with that directory 100 as the working directory, so you do not need to worry about this. 101 102 For examples of plugins, take a look at 103 [capnpc-capnp](https://github.com/sandstorm-io/capnproto/blob/master/c%2B%2B/src/capnp/compiler/capnpc-capnp.c%2B%2B) 104 or [capnpc-c++](https://github.com/sandstorm-io/capnproto/blob/master/c%2B%2B/src/capnp/compiler/capnpc-c%2B%2B.c%2B%2B). 105 106 ### Supporting Dynamic Languages 107 108 Dynamic languages have no compile step. This makes it difficult to work `capnp compile` into the 109 workflow for such languages. Additionally, dynamic languages are often scripting languages that do 110 not support pointer arithmetic or any reasonably-performant alternative. 111 112 Fortunately, dynamic languages usually have facilities for calling native code. The best way to 113 support Cap'n Proto in a dynamic language, then, is to wrap the C++ library, in particular the 114 [C++ dynamic API](cxx.html#dynamic-reflection). This way you get reasonable performance while 115 still avoiding the need to generate any code specific to each schema. 116 117 To parse the schema files, use the `capnp::SchemaParser` class (defined in `capnp/schema-parser.h`). 118 This way, schemas are loaded at the same time as all the rest of the program's code -- at startup. 119 An advanced implementation might consider caching the compiled schemas in binary format, then 120 loading the cached version using `capnp::SchemaLoader`, similar to the way e.g. Python caches 121 compiled source files as `.pyc` bytecode, but that's up to you. 122 123 ### Testing Your Implementation 124 125 The easiest way to test that you've implemented the spec correctly is to use the `capnp` tool 126 to [encode](capnp-tool.html#encoding-messages) test inputs and 127 [decode](capnp-tool.html#decoding-messages) outputs.