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