cannam@62: ---
cannam@62: layout: page
cannam@62: title: The capnp Tool
cannam@62: ---
cannam@62: 
cannam@62: # The `capnp` Tool
cannam@62: 
cannam@62: Cap'n Proto comes with a command-line tool called `capnp` intended to aid development and
cannam@62: debugging.  This tool can be used to:
cannam@62: 
cannam@62: * Compile Cap'n Proto schemas to produce source code in multiple languages.
cannam@62: * Generate unique type IDs.
cannam@62: * Decode Cap'n Proto messages to human-readable text.
cannam@62: * Encode text representations of Cap'n Proto messages to binary.
cannam@62: * Evaluate and extract constants defined in Cap'n Proto schemas.
cannam@62: 
cannam@62: This page summarizes the functionality.  A complete reference on the command's usage can be
cannam@62: found by typing:
cannam@62: 
cannam@62:     capnp help
cannam@62: 
cannam@62: ## Compiling Schemas
cannam@62: 
cannam@62:     capnp compile -oc++ myschema.capnp
cannam@62: 
cannam@62: This generates files `myschema.capnp.h` and `myschema.capnp.c++` which contain C++ source code
cannam@62: corresponding to the types defined in `myschema.capnp`.  Options exist to control output location
cannam@62: and import paths.
cannam@62: 
cannam@62: The above example generates C++ code, but the tool is able to generate output in any language
cannam@62: for which a plugin is available.  Compiler plugins are just regular programs named
cannam@62: `capnpc-language`.  For example, the above command runs `capnpc-c++`.  [More on how to write
cannam@62: compiler plugins](otherlang.html#how-to-write-compiler-plugins).
cannam@62: 
cannam@62: Note that some Cap'n Proto implementations (especially for interpreted languages) do not require
cannam@62: generating source code.
cannam@62: 
cannam@62: ## Decoding Messages
cannam@62: 
cannam@62:     capnp decode myschema.capnp MyType < message.bin > message.txt
cannam@62: 
cannam@62: `capnp decode` reads a binary Cap'n Proto message from standard input and decodes it to a
cannam@62: human-readable text format (specifically, the format used for specifying constants and default
cannam@62: values in [the schema language](language.html)).  By default it
cannam@62: expects an unpacked message, but you can decode a
cannam@62: [packed](encoding.html#packing) message with the `--packed` flag.
cannam@62: 
cannam@62: ## Encoding Messages
cannam@62: 
cannam@62:     capnp encode myschema.capnp MyType < message.txt > message.bin
cannam@62: 
cannam@62: `capnp encode` is the opposite of `capnp decode`: it takes a text-format message on stdin and
cannam@62: encodes it to binary (possibly [packed](encoding.html#packing),
cannam@62: with the `--packed` flag).
cannam@62: 
cannam@62: This is mainly useful for debugging purposes, to build test data or to apply tweaks to data
cannam@62: decoded with `capnp decode`.  You should not rely on `capnp encode` for encoding data written
cannam@62: and maintained in text format long-term -- instead, use `capnp eval`, which is much more powerful.
cannam@62: 
cannam@62: ## Evaluating Constants
cannam@62: 
cannam@62:     capnp eval myschema.capnp myConstant
cannam@62: 
cannam@62: This prints the value of `myConstant`, a [const](language.html#constants) declaration, after
cannam@62: applying variable substitution.  It can also output the value in binary format (`--binary` or
cannam@62: `--packed`).
cannam@62: 
cannam@62: At first glance, this may seem no more interesting that `capnp encode`:  the syntax used to define
cannam@62: constants in schema files is the same as the format accepted by `capnp encode`, right?  There is,
cannam@62: however, a big difference:  constants in schema files may be defined in terms of other constants,
cannam@62: which may even be imported from other files.
cannam@62: 
cannam@62: As a result, `capnp eval` is a great basis for implementing config files.  For example, a large
cannam@62: company might maintain a production server that serves dozens of clients and needs configuration
cannam@62: information about each one.  Rather than maintaining the config as one enormous file, it can be
cannam@62: written as several separate files with a master file that imports the rest.
cannam@62: 
cannam@62: Such a configuration should be compiled to binary format using `capnp eval` before deployment,
cannam@62: in order to verify that there are no errors and to make deployment easier and faster.  While you
cannam@62: could technically ship the text configs to production and have the servers parse them directly
cannam@62: (e.g. with `capnp::SchemaParser`), encoding before deployment is more efficient and robust.