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