Cap'n Proto is in BETA
cannam@147: cannam@147: cannam@147: cannam@147: As of this writing, Cap'n Proto is in beta. The serialization layer is close to feature-complete cannam@147: and we don't anticipate any further changes to the wire format. That said, if you want to use it, cannam@147: you should keep in mind some caveats: cannam@147: cannam@147: * **Security:** Cap'n Proto has not yet had a security review. Although Kenton has a background cannam@147: in security and is not aware of any vulnerabilities in the current code, it's likely that there cannam@147: are a few, and [some have been found](https://github.com/sandstorm-io/capnproto/tree/master/security-advisories) cannam@147: in the past. For now, do not accept Cap'n Proto messages from parties you do not trust. cannam@147: * **API Stability:** The Cap'n Proto programming interface may still change in ways that break cannam@147: existing code. Such changes are likely to be minor and should not affect the wire format. cannam@147: * **Performance:** While Cap'n Proto is inherently fast by design, the implementation has not yet cannam@147: undergone serious profiling and optimization. Currently it only beats Protobufs in realistic-ish cannam@147: end-to-end benchmarks by around 2x-5x. We can do better. cannam@147: * **RPC:** The RPC implementation particularly experimental, though it is used heavily by cannam@147: [Sandstorm.io](https://sandstorm.io). cannam@147: cannam@147: If you'd like to hack on Cap'n Proto, you should join the cannam@147: [discussion group](https://groups.google.com/group/capnproto)! cannam@147: cannam@147: If you'd just like to receive updates as things progress, add yourself to the cannam@147: [announce list](https://groups.google.com/group/capnproto-announce). cannam@147: cannam@147: ## Prerequisites cannam@147: cannam@147: ### Supported Compilers cannam@147: cannam@147: Cap'n Proto makes extensive use of C++11 language features. As a result, it requires a relatively cannam@147: new version of a well-supported compiler. The minimum versions are: cannam@147: cannam@147: * GCC 4.8 cannam@147: * Clang 3.3 cannam@147: * Visual C++ 2015 cannam@147: cannam@147: If your system's default compiler is older that the above, you will need to install a newer cannam@147: compiler and set the `CXX` environment variable before trying to build Cap'n Proto. For example, cannam@147: after installing GCC 4.8, you could set `CXX=g++-4.8` to use this compiler. cannam@147: cannam@147: ### Supported Operating Systems cannam@147: cannam@147: In theory, Cap'n Proto should work on any POSIX platform supporting one of the above compilers, cannam@147: as well as on Windows. We test every Cap'n Proto release on the following platforms: cannam@147: cannam@147: * Android cannam@147: * Linux cannam@147: * Mac OS X cannam@147: * Windows - Cygwin cannam@147: * Windows - MinGW-w64 cannam@147: * Windows - Visual C++ cannam@147: cannam@147: **Windows users:** Cap'n Proto requires Visual Studio 2015 Update 3 or newer. All runtime features cannam@147: of Cap'n Proto -- including serialization and RPC -- are now supported. (It is still not possible to cannam@147: compile the code generator tool, capnp.exe, using Visual Studio; however, a precompiled copy built cannam@147: with MinGW is provided in the release zip for your convenience.) cannam@147: cannam@147: **Mac OS X users:** You must use at least Xcode 5 with the Xcode command-line cannam@147: tools (Xcode menu > Preferences > Downloads). Alternatively, the command-line tools cannam@147: package from [Apple](https://developer.apple.com/downloads/) or compiler builds from cannam@147: [Macports](http://www.macports.org/), [Fink](http://www.finkproject.org/), or cannam@147: [Homebrew](http://brew.sh/) are reported to work. cannam@147: cannam@147: ## Installation: Unix cannam@147: cannam@147: **From Release Tarball** cannam@147: cannam@147: You may download and install the release version of Cap'n Proto like so: cannam@147: cannam@147:curl -O https://capnproto.org/capnproto-c++-0.6.0.tar.gz
cannam@147: tar zxf capnproto-c++-0.6.0.tar.gz
cannam@147: cd capnproto-c++-0.6.0
cannam@147: ./configure
cannam@147: make -j6 check
cannam@147: sudo make installhttps://capnproto.org/capnproto-c++-win32-0.6.0.zipcannam@147: cannam@147: 2. Find `capnp.exe`, `capnpc-c++.exe`, and `capnpc-capnp.exe` under `capnproto-tools-win32-0.6.0` in cannam@147: the zip and copy them somewhere. cannam@147: cannam@147: If you don't care about C++ support, you can stop here. The compiler exe can be used with plugins cannam@147: provided by projects implementing Cap'n Proto in other languages. cannam@147: cannam@147: If you want to use Cap'n Proto in C++ with Visual Studio, do the following: cannam@147: cannam@147: 1. Make sure that you are using Visual Studio 2015 or newer, with all updates installed. Cap'n cannam@147: Proto uses C++11 language features that did not work in previous versions of Visual Studio, cannam@147: and the updates include many bug fixes that Cap'n Proto requires. cannam@147: cannam@147: 2. Install [CMake](http://www.cmake.org/) version 3.1 or later. cannam@147: cannam@147: 3. Use CMake to generate Visual Studio project files under `capnproto-c++-0.6.0` in the zip file. cannam@147: You can use the CMake UI for this or run this shell command: cannam@147: cannam@147: cmake -G "Visual Studio 14 2015" cannam@147: cannam@147: (For VS2017, you can use "Visual Studio 15 2017" as the generator name.) cannam@147: cannam@147: 3. Open the "Cap'n Proto" solution in Visual Studio. cannam@147: cannam@147: 4. Adjust the project build options (e.g., choice of C++ runtime library, enable/disable exceptions cannam@147: and RTTI) to match the options of the project in which you plan to use Cap'n Proto. cannam@147: cannam@147: 5. Build the solution (`ALL_BUILD`). cannam@147: cannam@147: 6. Build the `INSTALL` project to copy the compiled libraries, tools, and header files into cannam@147: `CMAKE_INSTALL_PREFIX`. cannam@147: cannam@147: Alternatively, find the compiled `.lib` files in the build directory under cannam@147: `src/{capnp,kj}/{Debug,Release}` and place them somewhere where your project can link against them. cannam@147: Also add the `src` directory to your search path for `#include`s, or copy all the headers to your cannam@147: project's include directory. cannam@147: cannam@147: Cap'n Proto can also be built with MinGW or Cygwin, using the Unix/autotools build instructions. cannam@147: cannam@147: **From Git** cannam@147: cannam@147: The C++ sources are located under `c++` directory in the git repository. The build instructions are cannam@147: otherwise the same as for the release zip. cannam@147: