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