libs/beast/README.md

   1 <img width="880" height = "80" alt = "Boost.Beast Title"
   2     src="https://raw.githubusercontent.com/boostorg/beast/master/doc/images/readme2.png">
   3
   4 # HTTP and WebSocket built on Boost.Asio in C++11
   5
   6 Branch      | Linux/OSX | Windows | Coverage | Documentation | Matrix
   7 ------------|-----------|---------|----------|---------------|--------
   8 [master](https://github.com/boostorg/beast/tree/master)   | [![Build Status](https://travis-ci.org/boostorg/beast.svg?branch=master)](https://travis-ci.org/boostorg/beast)  | [![Build status](https://ci.appveyor.com/api/projects/status/2nh66khjjhtgasvo/branch/master?svg=true)](https://ci.appveyor.com/project/vinniefalco/beast/branch/master)   | [![codecov](https://img.shields.io/codecov/c/github/boostorg/beast/master.svg)](https://codecov.io/gh/boostorg/beast/branch/master)   | [![Documentation](https://img.shields.io/badge/documentation-master-brightgreen.svg)](http://www.boost.org/doc/libs/master/libs/beast/doc/html/index.html)  | [![Matrix](https://img.shields.io/badge/matrix-master-brightgreen.svg)](http://www.boost.org/development/tests/master/developer/beast.html)
   9 [develop](https://github.com/boostorg/beast/tree/develop) | [![Build Status](https://travis-ci.org/boostorg/beast.svg?branch=develop)](https://travis-ci.org/boostorg/beast) | [![Build status](https://ci.appveyor.com/api/projects/status/2nh66khjjhtgasvo/branch/develop?svg=true)](https://ci.appveyor.com/project/vinniefalco/beast/branch/develop) | [![codecov](https://img.shields.io/codecov/c/github/boostorg/beast/develop.svg)](https://codecov.io/gh/boostorg/beast/branch/develop) | [![Documentation](https://img.shields.io/badge/documentation-develop-brightgreen.svg)](https://www.boost.org/doc/libs/develop/libs/beast/index.html) | [![Matrix](https://img.shields.io/badge/matrix-develop-brightgreen.svg)](https://www.boost.org/development/tests/develop/developer/beast.html)
  10
  11 ## Contents
  12
  13 - [Introduction](#introduction)
  14 - [Appearances](#appearances)
  15 - [Description](#description)
  16 - [Requirements](#requirements)
  17 - [Git Branches](#branches)
  18 - [Building](#building)
  19 - [Usage](#usage)
  20 - [License](#license)
  21 - [Contact](#contact)
  22 - [Contributing](#contributing-we-need-your-help)
  23
  24 ## Introduction
  25
  26 Beast is a C++ header-only library serving as a foundation for writing
  27 interoperable networking libraries by providing **low-level HTTP/1,
  28 WebSocket, and networking protocol** vocabulary types and algorithms
  29 using the consistent asynchronous model of Boost.Asio.
  30
  31 This library is designed for:
  32
  33 * **Symmetry:** Algorithms are role-agnostic; build clients, servers, or both.
  34
  35 * **Ease of Use:** Boost.Asio users will immediately understand Beast.
  36
  37 * **Flexibility:** Users make the important decisions such as buffer or
  38   thread management.
  39
  40 * **Performance:** Build applications handling thousands of connections or more.
  41
  42 * **Basis for Further Abstraction.** Components are well-suited for building upon.
  43
  44 ## Appearances
  45
  46 | <a href="https://github.com/vinniefalco/CppCon2018">CppCon 2018</a> | <a href="https://www.bishopfox.com/case_study/securing-beast/">Bishop Fox 2018</a> |
  47 | ------------ | ------------ |
  48 | <a href="https://www.youtube.com/watch?v=7FQwAjELMek"><img width="320" height = "180" alt="Beast" src="https://raw.githubusercontent.com/vinniefalco/CppCon2018/master/CppCon2018.png"></a> | <a href="https://youtu.be/4TtyYbGDAj0"><img width="320" height = "180" alt="Beast Security Review" src="https://raw.githubusercontent.com/vinniefalco/BeastAssets/master/BishopFox2018.png"></a> |
  49
  50 | <a href="https://github.com/vinniefalco/CppCon2018">CppCon 2017</a> | <a href="http://cppcast.com/2017/01/vinnie-falco/">CppCast 2017</a> | <a href="https://raw.githubusercontent.com/vinniefalco/BeastAssets/master/CppCon2016.pdf">CppCon 2016</a> |
  51 | ------------ | ------------ | ----------- |
  52 | <a href="https://www.youtube.com/watch?v=WsUnnYEKPnI"><img width="320" height = "180" alt="Beast" src="https://raw.githubusercontent.com/vinniefalco/CppCon2017/master/CppCon2017.png"></a> | <a href="http://cppcast.com/2017/01/vinnie-falco/"><img width="180" height="180" alt="Vinnie Falco" src="https://avatars1.githubusercontent.com/u/1503976?v=3&u=76c56d989ef4c09625256662eca2775df78a16ad&s=180"></a> | <a href="https://www.youtube.com/watch?v=uJZgRcvPFwI"><img width="320" height = "180" alt="Beast" src="https://raw.githubusercontent.com/vinniefalco/BeastAssets/master/CppCon2016.png"></a> |
  53
  54 ## Description
  55
  56 This software is in its first official release. Interfaces
  57 may change in response to user feedback. For recent changes
  58 see the [CHANGELOG](CHANGELOG.md).
  59
  60 * [Official Site](https://github.com/boostorg/beast)
  61 * [Documentation](https://www.boost.org/doc/libs/master/libs/beast/) (master branch)
  62 * [Autobahn|Testsuite WebSocket Results](https://vinniefalco.github.io/boost/beast/reports/autobahn/index.html)
  63
  64 ## Requirements
  65
  66 This library is for programmers familiar with Boost.Asio. Users
  67 who wish to use asynchronous interfaces should already know how to
  68 create concurrent network programs using callbacks or coroutines.
  69
  70 * **C++11:** Robust support for most language features.
  71 * **Boost:** Boost.Asio and some other parts of Boost.
  72 * **OpenSSL:** Required for using TLS/Secure sockets and examples/tests
  73
  74 When using Microsoft Visual C++, Visual Studio 2017 or later is required.
  75
  76 One of these components is required in order to build the tests and examples:
  77
  78 * Properly configured bjam/b2
  79 * CMake 3.5.1 or later (Windows only)
  80
  81 ## Building
  82
  83 Beast is header-only. To use it just add the necessary `#include` line
  84 to your source files, like this:
  85 ```C++
  86 #include <boost/beast.hpp>
  87 ```
  88
  89 If you use coroutines you'll need to link with the Boost.Coroutine
  90 library. Please visit the Boost documentation for instructions
  91 on how to do this for your particular build system.
  92
  93 ## GitHub
  94
  95 To use the latest official release of Beast, simply obtain the latest
  96 Boost distribution and follow the instructions for integrating it
  97 into your development environment. If you wish to build the examples
  98 and tests, or if you wish to preview upcoming changes and features,
  99 it is suggested to clone the "Boost superproject" and work with Beast
 100 "in-tree" (meaning, the libs/beast subdirectory of the superproject).
 101
 102 The official repository contains the following branches:
 103
 104 * [**master**](https://github.com/boostorg/beast/tree/master) This
 105   holds the most recent snapshot with code that is known to be stable.
 106
 107 * [**develop**](https://github.com/boostorg/beast/tree/develop) This
 108   holds the most recent snapshot. It may contain unstable code.
 109
 110 Each of these branches requires a corresponding Boost branch and
 111 all of its subprojects. For example, if you wish to use the **master**
 112 branch version of Beast, you should clone the Boost superproject,
 113 switch to the **master** branch in the superproject and acquire
 114 all the Boost libraries corresponding to that branch including Beast.
 115
 116 To clone the superproject locally, and switch into the main project's
 117 directory use:
 118 ```
 119 git clone --recursive https://github.com/boostorg/boost.git
 120 cd boost
 121 ```
 122
 123 "bjam" is used to build Beast and the Boost libraries. On a non-Windows
 124 system use this command to build bjam:
 125 ```
 126 ./bootstrap.sh
 127 ```
 128
 129 From a Windows command line, build bjam using this command:
 130 ```
 131 .\BOOTSTRAP.BAT
 132 ```
 133
 134 ## Building tests and examples
 135 Building tests and examples requires OpenSSL installed. If OpenSSL is installed
 136 in a non-system location, you will need to copy the
 137 [user-config.jam](tools/user-config.jam) file into your home directory and set
 138 the `OPENSSL_ROOT` environment variable to the path that contains an installation
 139 of OpenSSL.
 140
 141 ### Ubuntu/Debian
 142 If installed into a system directory, OpenSSL will be automatically found and used.
 143 ```bash
 144 sudo apt install libssl-dev
 145 ```
 146 ### Windows
 147 Replace `path` in the following code snippets with the path you installed vcpkg
 148 to. Examples assume a 32-bit build, if you build a 64-bit version replace
 149 `x32-windows` with `x64-windows` in the path.
 150 - Using [vcpkg](https://github.com/Microsoft/vcpkg) and CMD:
 151 ```bat
 152 vcpkg install openssl --triplet x32-windows
 153 SET OPENSSL_ROOT=path\installed\x32-windows
 154 ```
 155
 156 - Using [vcpkg](https://github.com/Microsoft/vcpkg) and PowerShell:
 157 ```powershell
 158 vcpkg install openssl --triplet x32-windows
 159 $env:OPENSSL_ROOT = "path\x32-windows"
 160 ```
 161
 162 - Using [vcpkg](https://github.com/Microsoft/vcpkg) and bash:
 163 ```bash
 164 vcpkg.exe install openssl --triplet x32-windows
 165 export OPENSSL_ROOT=path/x32-windows
 166 ```
 167
 168 ### Mac OS
 169 Using [brew](https://github.com/Homebrew/brew):
 170 ```bash
 171 brew install openssl
 172 export OPENSSL_ROOT=$(brew --prefix openssl)
 173 # install bjam tool user specific configuration file to read OPENSSL_ROOT
 174 # see https://boostorg.github.io/build/manual/develop/index.html
 175 cp ./libs/beast/tools/user-config.jam $HOME
 176 ```
 177
 178 Make sure the bjam tool (also called "b2") is available in the path
 179 your shell uses to find executables. The Beast project is located in
 180 "libs/beast" relative to the directory containing the Boot superproject.
 181 To build the Beast tests, examples, and documentation use these commands:
 182 ```
 183 export PATH=$PWD:$PATH
 184 b2 -j2 libs/beast/test cxxstd=11      # bjam must be in your $PATH
 185 b2 -j2 libs/beast/example cxxstd=11   # "-j2" means use two processors
 186 b2 libs/beast/doc                     # Doxygen and Saxon are required for this
 187 ```
 188
 189
 190
 191 Additional instructions for configuring, using, and building libraries
 192 in superproject may be found in the
 193 [Boost Wiki](https://github.com/boostorg/boost/wiki/Getting-Started).
 194
 195 ## Visual Studio
 196
 197 CMake may be used to generate a very nice Visual Studio solution and
 198 a set of Visual Studio project files using these commands:
 199
 200 ```
 201 cd libs/beast
 202 mkdir bin
 203 cd bin
 204 cmake ..                                    # for 32-bit Windows builds, or
 205 cmake -G"Visual Studio 15 2017 Win64" ..    # for 64-bit Windows builds (VS2017)
 206 ```
 207
 208 The files in the repository are laid out thusly:
 209
 210 ```
 211 ./
 212     bin/            Create this to hold executables and project files
 213     bin64/          Create this to hold 64-bit Windows executables and project files
 214     doc/            Source code and scripts for the documentation
 215     include/        Where the header files are located
 216     example/        Self contained example programs
 217     meta/           Metadata for Boost integration
 218     test/           The unit tests for Beast
 219     tools/          Scripts used for CI testing
 220 ```
 221
 222 ## Usage
 223
 224 These examples are complete, self-contained programs that you can build
 225 and run yourself (they are in the `example` directory).
 226
 227 https://www.boost.org/doc/libs/develop/libs/beast/doc/html/beast/quick_start.html
 228
 229 ## License
 230
 231 Distributed under the Boost Software License, Version 1.0.
 232 (See accompanying file [LICENSE_1_0.txt](LICENSE_1_0.txt) or copy at
 233 https://www.boost.org/LICENSE_1_0.txt)
 234
 235 ## Contact
 236
 237 Please report issues or questions here:
 238 https://github.com/boostorg/beast/issues
 239
 240 ---
 241
 242 ## Contributing (We Need Your Help!)
 243
 244 If you would like to contribute to Beast and help us maintain high
 245 quality, consider performing code reviews on active pull requests.
 246 Any feedback from users and stakeholders, even simple questions about
 247 how things work or why they were done a certain way, carries value
 248 and can be used to improve the library. Code review provides these
 249 benefits:
 250
 251 * Identify bugs
 252 * Documentation proof-reading
 253 * Adjust interfaces to suit use-cases
 254 * Simplify code
 255
 256 You can look through the Closed pull requests to get an idea of how
 257 reviews are performed. To give a code review just sign in with your
 258 GitHub account and then add comments to any open pull requests below,
 259 don't be shy!
 260 <p>https://github.com/boostorg/beast/pulls</p>
 261
 262 Here are some resources to learn more about
 263 code reviews:
 264
 265 * <a href="https://blog.scottnonnenberg.com/top-ten-pull-request-review-mistakes/">Top 10 Pull Request Review Mistakes</a>
 266 * <a href="https://smartbear.com/SmartBear/media/pdfs/best-kept-secrets-of-peer-code-review.pdf">Best Kept Secrets of Peer Code Review (pdf)</a>
 267 * <a href="http://support.smartbear.com/support/media/resources/cc/11_Best_Practices_for_Peer_Code_Review.pdf">11 Best Practices for Peer Code Review (pdf)</a>
 268 * <a href="http://www.evoketechnologies.com/blog/code-review-checklist-perform-effective-code-reviews/">Code Review Checklist – To Perform Effective Code Reviews</a>
 269 * <a href="https://www.codeproject.com/Articles/524235/Codeplusreviewplusguidelines">Code review guidelines</a>
 270 * <a href="https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md">C++ Core Guidelines</a>
 271 * <a href="https://doc.lagout.org/programmation/C/CPP101.pdf">C++ Coding Standards (Sutter & Andrescu)</a>
 272
 273 Beast thrives on code reviews and any sort of feedback from users and
 274 stakeholders about its interfaces. Even if you just have questions,
 275 asking them in the code review or in issues provides valuable information
 276 that can be used to improve the library - do not hesitate, no question
 277 is insignificant or unimportant!