install.md 5.22 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
# Installation: Tools and C++ Runtime
Kenton Varda's avatar
Kenton Varda committed
7

8 9 10
<div style="float: right"><a class="groups_link" style="color: #fff"
href="https://groups.google.com/group/capnproto-announce">Get Notified of Updates</a></div>

11 12
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
13 14 15 16 17
development language is something else.

This package is licensed under the [MIT License](http://opensource.org/licenses/MIT).

## Prerequisites
Kenton Varda's avatar
Kenton Varda committed
18

19
### Supported Compilers
Kenton Varda's avatar
Kenton Varda committed
20

21 22
Cap'n Proto makes extensive use of C++11 language features. As a result, it requires a relatively
new version of a well-supported compiler. The minimum versions are:
23

24
* GCC 4.9
25
* Clang 3.5
26
* Visual C++ 2017
Kenton Varda's avatar
Kenton Varda committed
27

28 29
If your system's default compiler is older that the above, you will need to install a newer
compiler and set the `CXX` environment variable before trying to build Cap'n Proto. For example,
30
after installing GCC 4.9, you could set `CXX=g++-4.9` to use this compiler.
Kenton Varda's avatar
Kenton Varda committed
31

32
### Supported Operating Systems
Kenton Varda's avatar
Kenton Varda committed
33

34 35
In theory, Cap'n Proto should work on any POSIX platform supporting one of the above compilers,
as well as on Windows. We test every Cap'n Proto release on the following platforms:
36

37 38
* Android
* Linux
39
* Mac OS X
40
* Windows - Cygwin
41 42
* Windows - MinGW-w64
* Windows - Visual C++
43

44
**Windows users:** Cap'n Proto requires Visual Studio 2017 or newer. All features
45
of Cap'n Proto -- including serialization, dynamic API, RPC, and schema parser -- are now supported.
46

47
**Mac OS X users:** You should use the latest Xcode with the Xcode command-line
48 49
tools (Xcode menu > Preferences > Downloads).  Alternatively, the command-line tools
package from [Apple](https://developer.apple.com/downloads/) or compiler builds from
50 51
[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
52

53
## Installation: Unix
Kenton Varda's avatar
Kenton Varda committed
54

55 56
**From Release Tarball**

Kenton Varda's avatar
Kenton Varda committed
57 58
You may download and install the release version of Cap'n Proto like so:

59
<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>
60 61
tar zxf capnproto-c++-0.0.0.tar.gz
cd capnproto-c++-0.0.0
Kenton Varda's avatar
Kenton Varda committed
62 63 64 65 66 67 68 69
./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`.

70 71 72 73 74 75 76 77 78
**From Package Managers**

Some package managers include Cap'n Proto packages.

Note: These packages are not maintained by us and are sometimes not up to date with the latest Cap'n Proto release.

* Debian / Ubuntu: `apt-get install capnproto`
* Homebrew (OSX): `brew install capnp`

79
**From Git**
Kenton Varda's avatar
Kenton Varda committed
80

81
If you download directly from Git, you will need to have the GNU autotools --
Kenton Varda's avatar
Kenton Varda committed
82 83
[autoconf](http://www.gnu.org/software/autoconf/),
[automake](http://www.gnu.org/software/automake/), and
84
[libtool](http://www.gnu.org/software/libtool/) -- installed.
Kenton Varda's avatar
Kenton Varda committed
85

86
    git clone https://github.com/sandstorm-io/capnproto.git
Kenton Varda's avatar
Kenton Varda committed
87 88 89 90 91 92
    cd capnproto/c++
    autoreconf -i
    ./configure
    make -j6 check
    sudo make install

93
## Installation: Windows
Kenton Varda's avatar
Kenton Varda committed
94

95 96
**From Release Zip**

97
1. Download Cap'n Proto Win32 build:
Kenton Varda's avatar
Kenton Varda committed
98

99
   <pre><a href="https://capnproto.org/capnproto-c++-win32-0.0.0.zip">https://capnproto.org/capnproto-c++-win32-0.0.0.zip</a></pre>
100

101
2. Find `capnp.exe`, `capnpc-c++.exe`, and `capnpc-capnp.exe` under `capnproto-tools-win32-0.0.0` in
102
   the zip and copy them somewhere.
103

104 105
If you don't care about C++ support, you can stop here. The compiler exe can be used with plugins
provided by projects implementing Cap'n Proto in other languages.
Kenton Varda's avatar
Kenton Varda committed
106

107
If you want to use Cap'n Proto in C++ with Visual Studio, do the following:
Kenton Varda's avatar
Kenton Varda committed
108

109
1. Make sure that you are using Visual Studio 2017 or newer, with all updates installed. Cap'n
110 111
   Proto uses C++11 language features that did not work in previous versions of Visual Studio,
   and the updates include many bug fixes that Cap'n Proto requires.
Kenton Varda's avatar
Kenton Varda committed
112

113
2. Install [CMake](http://www.cmake.org/) version 3.1 or later.
Kenton Varda's avatar
Kenton Varda committed
114

115 116
3. Use CMake to generate Visual Studio project files under `capnproto-c++-0.0.0` in the zip file.
   You can use the CMake UI for this or run this shell command:
Kenton Varda's avatar
Kenton Varda committed
117

118
       cmake -G "Visual Studio 15 2017"
119

120
3. Open the "Cap'n Proto" solution in Visual Studio.
Kenton Varda's avatar
Kenton Varda committed
121

122 123
4. Adjust the project build options (e.g., choice of C++ runtime library, enable/disable exceptions
   and RTTI) to match the options of the project in which you plan to use Cap'n Proto.
Kenton Varda's avatar
Kenton Varda committed
124

125
5. Build the solution (`ALL_BUILD`).
Kenton Varda's avatar
Kenton Varda committed
126

127 128
6. Build the `INSTALL` project to copy the compiled libraries, tools, and header files into
   `CMAKE_INSTALL_PREFIX`.
129

130 131 132 133
   Alternatively, find the compiled `.lib` files in the build directory under
   `src/{capnp,kj}/{Debug,Release}` and place them somewhere where your project can link against them.
   Also add the `src` directory to your search path for `#include`s, or copy all the headers to your
   project's include directory.
Kenton Varda's avatar
Kenton Varda committed
134

135
Cap'n Proto can also be built with MinGW or Cygwin, using the Unix/autotools build instructions.
Kenton Varda's avatar
Kenton Varda committed
136

137
**From Git**
Kenton Varda's avatar
Kenton Varda committed
138

139 140
The C++ sources are located under `c++` directory in the git repository. The build instructions are
otherwise the same as for the release zip.
Kenton Varda's avatar
Kenton Varda committed
141