capnp-tool.md (3712B)
1 --- 2 layout: page 3 title: The capnp Tool 4 --- 5 6 # The `capnp` Tool 7 8 Cap'n Proto comes with a command-line tool called `capnp` intended to aid development and 9 debugging. This tool can be used to: 10 11 * Compile Cap'n Proto schemas to produce source code in multiple languages. 12 * Generate unique type IDs. 13 * Decode Cap'n Proto messages to human-readable text. 14 * Encode text representations of Cap'n Proto messages to binary. 15 * Evaluate and extract constants defined in Cap'n Proto schemas. 16 17 This page summarizes the functionality. A complete reference on the command's usage can be 18 found by typing: 19 20 capnp help 21 22 ## Compiling Schemas 23 24 capnp compile -oc++ myschema.capnp 25 26 This generates files `myschema.capnp.h` and `myschema.capnp.c++` which contain C++ source code 27 corresponding to the types defined in `myschema.capnp`. Options exist to control output location 28 and import paths. 29 30 The above example generates C++ code, but the tool is able to generate output in any language 31 for which a plugin is available. Compiler plugins are just regular programs named 32 `capnpc-language`. For example, the above command runs `capnpc-c++`. [More on how to write 33 compiler plugins](otherlang.html#how-to-write-compiler-plugins). 34 35 Note that some Cap'n Proto implementations (especially for interpreted languages) do not require 36 generating source code. 37 38 ## Decoding Messages 39 40 capnp decode myschema.capnp MyType < message.bin > message.txt 41 42 `capnp decode` reads a binary Cap'n Proto message from standard input and decodes it to a 43 human-readable text format (specifically, the format used for specifying constants and default 44 values in [the schema language](language.html)). By default it 45 expects an unpacked message, but you can decode a 46 [packed](encoding.html#packing) message with the `--packed` flag. 47 48 ## Encoding Messages 49 50 capnp encode myschema.capnp MyType < message.txt > message.bin 51 52 `capnp encode` is the opposite of `capnp decode`: it takes a text-format message on stdin and 53 encodes it to binary (possibly [packed](encoding.html#packing), 54 with the `--packed` flag). 55 56 This is mainly useful for debugging purposes, to build test data or to apply tweaks to data 57 decoded with `capnp decode`. You should not rely on `capnp encode` for encoding data written 58 and maintained in text format long-term -- instead, use `capnp eval`, which is much more powerful. 59 60 ## Evaluating Constants 61 62 capnp eval myschema.capnp myConstant 63 64 This prints the value of `myConstant`, a [const](language.html#constants) declaration, after 65 applying variable substitution. It can also output the value in binary format (`--binary` or 66 `--packed`). 67 68 At first glance, this may seem no more interesting than `capnp encode`: the syntax used to define 69 constants in schema files is the same as the format accepted by `capnp encode`, right? There is, 70 however, a big difference: constants in schema files may be defined in terms of other constants, 71 which may even be imported from other files. 72 73 As a result, `capnp eval` is a great basis for implementing config files. For example, a large 74 company might maintain a production server that serves dozens of clients and needs configuration 75 information about each one. Rather than maintaining the config as one enormous file, it can be 76 written as several separate files with a master file that imports the rest. 77 78 Such a configuration should be compiled to binary format using `capnp eval` before deployment, 79 in order to verify that there are no errors and to make deployment easier and faster. While you 80 could technically ship the text configs to production and have the servers parse them directly 81 (e.g. with `capnp::SchemaParser`), encoding before deployment is more efficient and robust.