annotate src/capnproto-0.6.0/doc/otherlang.md @ 84:08ae793730bd

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