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