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