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