install.md 9.2 KB
Newer Older
Kenton Varda's avatar
Kenton Varda committed
1 2
---
layout: page
Kenton Varda's avatar
Kenton Varda committed
3
title: Installation
Kenton Varda's avatar
Kenton Varda committed
4 5 6 7
---

# Installation

8
<p style="font-size: 125%; font-weight: bold;">Note: Cap'n Proto is in BETA</p>
9

Kenton Varda's avatar
Kenton Varda committed
10 11
<div style="float: right"><a class="groups_link" style="color: #fff"
href="https://groups.google.com/group/capnproto-announce">Sign Up for Updates</a></div>
Kenton Varda's avatar
Kenton Varda committed
12

13 14 15
As of this writing, Cap'n Proto is in beta.  The serialization layer is close to feature-complete
and we don't anticipate any further changes to the wire format.  That said, if you want to use it,
you should keep in mind some caveats:
Kenton Varda's avatar
Kenton Varda committed
16

Kenton Varda's avatar
Kenton Varda committed
17 18 19
* **Security:** Cap'n Proto has not yet had a security review.  Although Kenton has a background
  in security and is not aware of any vulnerabilities in the current code, it's likely that there
  are a few.  For now, do not accept Cap'n Proto messages from parties you do not trust.
20 21
* **API Stability:** The Cap'n Proto programming interface may still change in ways that break
  existing code.  Such changes are likely to be minor and should not affect the wire format.
Kenton Varda's avatar
Kenton Varda committed
22
* **Performance:** While Cap'n Proto is inherently fast by design, the implementation has not yet
23 24
  undergone serious profiling and optimization.  Currently it only beats Protobufs in realistic-ish
  end-to-end benchmarks by around 2x-5x.  We can do better.
25 26 27
* **RPC:** The RPC implementation is very new (introduced in v0.4 / Dec 2013).  It is missing many
  features that are essential in real-world use (like timeouts), the interface is still in flux,
  and it needs a lot of optimization work.
28

29 30
If you'd like to hack on Cap'n Proto, you should join the
[discussion group](https://groups.google.com/group/capnproto)!
Kenton Varda's avatar
Kenton Varda committed
31

32
If you'd just like to receive updates as things progress, add yourself to the
33
[announce list](https://groups.google.com/group/capnproto-announce).
Kenton Varda's avatar
Kenton Varda committed
34

35
## Installing the Cap'n Proto tools and C++ Runtime
Kenton Varda's avatar
Kenton Varda committed
36

37 38 39
The Cap'n Proto tools, including the compiler which takes `.capnp` files and generates source code
for them, are written in C++.  Therefore, you must install the C++ package even if your actual
development language is something else.
Kenton Varda's avatar
Kenton Varda committed
40

Kenton Varda's avatar
Kenton Varda committed
41
This package is licensed under the [MIT License](http://opensource.org/licenses/MIT).
42

Kenton Varda's avatar
Kenton Varda committed
43
### GCC 4.7 or Clang 3.2 Needed
Kenton Varda's avatar
Kenton Varda committed
44 45

If you are using GCC, you MUST use at least version 4.7 as Cap'n Proto uses recently-implemented
Kenton Varda's avatar
Kenton Varda committed
46 47 48 49 50
C++11 features.  If GCC 4.7 is installed but your system's default GCC is older, you will probably
need to set the environment variable `CXX=g++-4.7` before following the instructions below.

If you are using Clang, you must use at least version 3.2.  To use Clang, set the environment
variable `CXX=clang++` before following any instructions below, otherwise `g++` is used by default.
Kenton Varda's avatar
Kenton Varda committed
51

52 53
This package is officially tested on Linux (GCC 4.7, GCC 4.8, Clang 3.2), Mac OSX (Xcode 5), and
Cygwin (Windows; GCC 4.8), in 32-bit and 64-bit modes.
54

55 56 57 58
Mac/Xcode users:  You must use at least Xcode 5, and you must download the Xcode command-line tools
under Xcode menu > Preferences > Downloads.  Alternatively, compiler builds from
[Macports](http://www.macports.org/), [Fink](http://www.finkproject.org/), or
[Homebrew](http://brew.sh/) are reported to work.
Kenton Varda's avatar
Kenton Varda committed
59

Kenton Varda's avatar
Kenton Varda committed
60
Sorry, but Microsoft Visual Studio 2013
61
[does not implement enough of C++11](faq.html#can-i-use-capn-proto-with-visual-studio-pleeeeeaaaaassssseeeee)
Kenton Varda's avatar
Kenton Varda committed
62 63 64
to compile Cap'n Proto.  We hope that the Internet Explorer of compilers will catch up in one of
the upcoming CTPs (the November 2013 CTP is almost there).

Kenton Varda's avatar
Kenton Varda committed
65 66 67 68
### Building from a release package

You may download and install the release version of Cap'n Proto like so:

69
<pre><code>curl -O <a href="https://capnproto.org/capnproto-c++-0.0.0.tar.gz">https://capnproto.org/capnproto-c++-0.0.0.tar.gz</a>
70 71
tar zxf capnproto-c++-0.0.0.tar.gz
cd capnproto-c++-0.0.0
Kenton Varda's avatar
Kenton Varda committed
72 73 74 75 76 77 78 79 80 81 82
./configure
make -j6 check
sudo make install</code></pre>

This will install `capnp`, the Cap'n Proto command-line tool.  It will also install `libcapnp`,
`libcapnpc`, and `libkj` in `/usr/local/lib` and headers in `/usr/local/include/capnp` and
`/usr/local/include/kj`.

### Building from Git with Autotools

If you download directly from Git, and you don't want to
83
[build with Ekam](install.html#building-with-ekam), you will need to have the GNU autotools --
Kenton Varda's avatar
Kenton Varda committed
84 85 86 87 88 89 90 91 92 93 94 95 96 97
[autoconf](http://www.gnu.org/software/autoconf/),
[automake](http://www.gnu.org/software/automake/), and
[libtool](http://www.gnu.org/software/libtool/) -- installed.  You will also need Subversion
installed (in addition to Git) in order to fetch the Google Test sources (done by
`setup-autotools.sh`).

    git clone https://github.com/kentonv/capnproto.git
    cd capnproto/c++
    ./setup-autotools.sh
    autoreconf -i
    ./configure
    make -j6 check
    sudo make install

Kenton Varda's avatar
Kenton Varda committed
98 99 100 101 102 103 104
### Building with Ekam

Ekam is a build system I wrote a while back that automatically figures out how to build your C++
code without instructions.  It also supports continuous builds, where it watches the filesystem for
changes (via inotify) and immediately rebuilds as necessary.  Instant feedback is key to
productivity, so I really like using Ekam.

Kenton Varda's avatar
Kenton Varda committed
105
Unfortunately it's very much unfinished.  It works (for me), but it is quirky and rough around the
106
edges.  It only works on Linux, and is best used together with Eclipse.  If you find it
107
unacceptable, scroll up to the [Automake instructions](#building-from-git-with-autotools).
Kenton Varda's avatar
Kenton Varda committed
108 109 110 111 112 113 114

The Cap'n Proto repo includes a script which will attempt to set up Ekam for you.

    git clone https://github.com/kentonv/capnproto.git
    cd capnproto/c++
    ./setup-ekam.sh

Kenton Varda's avatar
Kenton Varda committed
115 116
If all goes well, this downloads the Ekam code into a directory called `.ekam` and adds some
symlinks under src.  It also imports the [Google Test](https://googletest.googlecode.com) and
Kenton Varda's avatar
Kenton Varda committed
117 118 119 120
[Protobuf](http://protobuf.googlecode.com) source code, so you can compile tests and benchmarks.

Once Ekam is installed, you can do:

Kenton Varda's avatar
Kenton Varda committed
121
    make -f Makefile.ekam once
Kenton Varda's avatar
Kenton Varda committed
122

Kenton Varda's avatar
Kenton Varda committed
123
This will build everything it can and run tests.
124 125

Note that Ekam will fail to build some things and output a bunch of error messages.  You should
126 127 128
be able to ignore any errors that originate outside of the `capnp` and `kj` directories -- these
are just parts of other packages like Google Test that Ekam doesn't fully know how to build, but
aren't needed by Cap'n Proto anyway.
129

130
#### Running the Benchmarks
Kenton Varda's avatar
Kenton Varda committed
131 132 133 134 135 136 137 138 139

Before getting into benchmarks, let me be frank:  performance varies wildly by use case, and no
benchmark is going to properly reflect the big picture.  If performance is critical to your use
case, you should write a benchmark specific to your case, and test multiple serialization
technologies.  Don't assume anything.  If you find Cap'n Proto performs sub-optimally, though,
[tell us about it](https://groups.google.com/group/capnproto).

That said, Cap'n Proto does have a small suite of silly benchmarks used to validate changes.

140
The Ekam build will put the benchmark binaries in `tmp/capnp/benchmark`.
Kenton Varda's avatar
Kenton Varda committed
141

Kenton Varda's avatar
Kenton Varda committed
142
    tmp/capnp/benchmark/runner
Kenton Varda's avatar
Kenton Varda committed
143 144 145 146 147 148 149 150 151 152

This runs the default test case, CatRank.  CatRank simulates a search engine scoring algorithm
which promotes pages that discuss cats (and demotes ones discussing dogs).  A list of up to 1000
random search results with URLs, scores, and snippets is sent to the server, which searches the
snippets for instances of "cat" and "dog", adjusts their scores accordingly, then returns the new
result list sorted by score.

This test case is very string-heavy.  Cap'n Proto performs well due to its zero-copy strings, but
packing the message doesn't help much.

Kenton Varda's avatar
Kenton Varda committed
153
    tmp/capnp/benchmark/runner eval
Kenton Varda's avatar
Kenton Varda committed
154 155 156 157 158 159 160

In this test case, the client generates a random, deeply-nested arithmetic expression for the
server to evaluate.  This case is a pathologically bad case for Cap'n Proto as it involves lots of
pointers with relatively little actual data.  When packing is enabled it actually loses to
Protobufs by a little bit on CPU time (as of this writing, at least; it'll probably get better with
optimization).

Kenton Varda's avatar
Kenton Varda committed
161
    tmp/capnp/benchmark/runner carsales
Kenton Varda's avatar
Kenton Varda committed
162 163 164 165 166

This test case involves sending to the server a description of a bunch of cars, and asks the server
to decide how much the lot is worth.  This case is very number-heavy, and because of this
Cap'n Proto's "packed" mode really shines.

167
#### Developing with Ekam
Kenton Varda's avatar
Kenton Varda committed
168 169 170 171 172 173

If you intend to do some development, you should build `continuous` or `continuous-opt` instead
of `once`.  These modes will build everything, then watch the source tree for changes and rebuild
as necessary.  `continuous` does a debug build while `continuous-opt` optimizes; the former is best
while developing but don't run the benchmarks in debug mode!

Kenton Varda's avatar
Kenton Varda committed
174
If you use Eclipse, you should use the Ekam Eclipse plugin to get build results fed back into your
Kenton Varda's avatar
Kenton Varda committed
175
editor while building in continuous mode.  Build the plugin like so:
Kenton Varda's avatar
Kenton Varda committed
176 177 178 179 180 181 182 183 184 185 186

1. Open the `.ekam/eclipse` directory as an Eclipse project.
2. File -> Export -> Plug-in Development -> Deployable Plug-ins and Fragments.
3. Choose the Ekam Dashboard project and export to your Eclipse directory, or export to another
   directory and copy the files into your Eclipse directory.
4. Restart Eclipse.
5. Make sure you have some sort of project in your work space containing your Ekam source tree. It
   should be rooted at the directory containing "src", "tmp", etc. The plugin will mark errors
   within this project.
6. Window -> Show View -> Other -> Ekam -> Ekam Dashboard

Kenton Varda's avatar
Kenton Varda committed
187 188
The dashboard view lets you browse the whole tree of build actions and also populates your editor
with error markers.