ceph/src/boost/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/g0llpbvhpjuxjnlw/branch/master?svg=true)](https://ci.appveyor.com/project/vinniefalco/beast/branch/master)   | [![codecov](https://codecov.io/gh/boostorg/Beast/branch/master/graph/badge.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/g0llpbvhpjuxjnlw/branch/develop?svg=true)](https://ci.appveyor.com/project/vinniefalco/beast/branch/develop) | [![codecov](https://codecov.io/gh/boostorg/Beast/branch/develop/graph/badge.svg)](https://codecov.io/gh/boostorg/beast/branch/develop) | [![Documentation](https://img.shields.io/badge/documentation-develop-brightgreen.svg)](http://www.boost.org/doc/libs/develop/libs/beast/index.html) | [![Matrix](https://img.shields.io/badge/matrix-develop-brightgreen.svg)](http://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 - [Building](#building)
  18 - [Usage](#usage)
  19 - [License](#license)
  20 - [Contact](#contact)
  21 - [Contributing](#Contributing)
  22
  23 ## Introduction
  24
  25 Beast is a C++ header-only library serving as a foundation for writing
  26 interoperable networking libraries by providing **low-level HTTP/1,
  27 WebSocket, and networking protocol** vocabulary types and algorithms
  28 using the consistent asynchronous model of Boost.Asio.
  29
  30 This library is designed for:
  31
  32 * **Symmetry:** Algorithms are role-agnostic; build clients, servers, or both.
  33
  34 * **Ease of Use:** Boost.Asio users will immediately understand Beast.
  35
  36 * **Flexibility:** Users make the important decisions such as buffer or
  37   thread management.
  38
  39 * **Performance:** Build applications handling thousands of connections or more.
  40
  41 * **Basis for Further Abstraction.** Components are well-suited for building upon.
  42
  43 ## Appearances
  44
  45 | <a href="https://raw.githubusercontent.com/vinniefalco/CppCon2017/master/Make%20Classes%20Great%20Again%20-%20Vinnie%20Falco%20-%20CppCon%202017.pdf">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> |
  46 | ------------ | ------------ | ----------- |
  47 | <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> |
  48
  49 ## Description
  50
  51 This software is in its first official release. Interfaces
  52 may change in response to user feedback. For recent changes
  53 see the [CHANGELOG](CHANGELOG.md).
  54
  55 * [Official Site](https://github.com/boostorg/beast)
  56 * [Documentation](http://www.boost.org/doc/libs/master/libs/beast/) (master branch)
  57 * [Autobahn|Testsuite WebSocket Results](https://vinniefalco.github.io/boost/beast/reports/autobahn/index.html)
  58
  59 ## Requirements
  60
  61 This library is for programmers familiar with Boost.Asio. Users
  62 who wish to use asynchronous interfaces should already know how to
  63 create concurrent network programs using callbacks or coroutines.
  64
  65 * **C++11:** Robust support for most language features.
  66 * **Boost:** Boost.Asio and some other parts of Boost.
  67 * **OpenSSL:** Optional, for using TLS/Secure sockets.
  68
  69 When using Microsoft Visual C++, Visual Studio 2015 Update 3 or later is required.
  70
  71 One of these components is required in order to build the tests and examples:
  72
  73 * Properly configured bjam/b2
  74 * CMake 3.5.1 or later (Windows only)
  75
  76 ## Building
  77
  78 Beast is header-only. To use it just add the necessary `#include` line
  79 to your source files, like this:
  80 ```C++
  81 #include <boost/beast.hpp>
  82 ```
  83
  84 To build your program successfully, you'll need to add the Boost.System
  85 library to link with. If you use coroutines you'll also need to link
  86 with the Boost.Coroutine library. Please visit the Boost documentation
  87 for instructions on how to do this for your particular build system.
  88
  89 To build the documentation, examples, tests, and benchmarks it is
  90 necessary to first obtain the boost "superproject" along with all
  91 of the boost libraries. Instructions for doing so may be found on
  92 the [Boost Wiki](https://github.com/boostorg/boost/wiki/Getting-Started).
  93 These commamnds will build the programs and documentation that come
  94 with Beast (omit the cxxflags parameter when building using MSVC):
  95
  96 ```
  97 cd boost   # The directory containing the boost superproject and libraries
  98 b2 libs/beast/test cxxflags="-std=c++11"    # bjam must be in your $PATH
  99 b2 libs/beast/example cxxflags="-std=c++11"
 100 b2 libs/beast/doc
 101 ```
 102
 103 On Windows platforms only, CMake may be used to generate a Visual Studio
 104 solution and a set of Visual Studio project files using these commands:
 105
 106 ```
 107 cd boost   # The directory containing the boost superproject and libraries
 108 cd libs/beast
 109 mkdir bin
 110 cd bin
 111 cmake ..                                    # for 32-bit Windows builds, or
 112 cmake -G"Visual Studio 14 2015 Win64" ..    # for 64-bit Windows builds (VS2015), or
 113 cmake -G"Visual Studio 15 2017 Win64" ..    # for 64-bit Windows builds (VS2017)
 114 ```
 115
 116 The files in the repository are laid out thusly:
 117
 118 ```
 119 ./
 120     bin/            Create this to hold executables and project files
 121     bin64/          Create this to hold 64-bit Windows executables and project files
 122     doc/            Source code and scripts for the documentation
 123     include/        Where the header files live
 124     extras/         Additional APIs, may change
 125     example/        Self contained example programs
 126     meta/           Metadata for Boost integration
 127     scripts/        Small scripts used with CI systems
 128     test/           Unit tests
 129 ```
 130
 131 ## Usage
 132
 133 These examples are complete, self-contained programs that you can build
 134 and run yourself (they are in the `example` directory).
 135
 136 http://www.boost.org/doc/libs/develop/libs/beast/doc/html/beast/quick_start.html
 137
 138 ## License
 139
 140 Distributed under the Boost Software License, Version 1.0.
 141 (See accompanying file [LICENSE_1_0.txt](LICENSE_1_0.txt) or copy at
 142 http://www.boost.org/LICENSE_1_0.txt)
 143
 144 ## Contact
 145
 146 Please report issues or questions here:
 147 https://github.com/boostorg/beast/issues
 148
 149 ---
 150
 151 ## Contributing (We Need Your Help!)
 152
 153 If you would like to contribute to Beast and help us maintain high
 154 quality, consider performing code reviews on active pull requests.
 155 Any feedback from users and stakeholders, even simple questions about
 156 how things work or why they were done a certain way, carries value
 157 and can be used to improve the library. Code review provides these
 158 benefits:
 159
 160 * Identify bugs
 161 * Documentation proof-reading
 162 * Adjust interfaces to suit use-cases
 163 * Simplify code
 164
 165 You can look through the Closed pull requests to get an idea of how
 166 reviews are performed. To give a code review just sign in with your
 167 GitHub account and then add comments to any open pull requests below,
 168 don't be shy!
 169 <p>https://github.com/boostorg/beast/pulls</p>
 170
 171 Here are some resources to learn more about
 172 code reviews:
 173
 174 * <a href="https://blog.scottnonnenberg.com/top-ten-pull-request-review-mistakes/">Top 10 Pull Request Review Mistakes</a>
 175 * <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>
 176 * <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>
 177 * <a href="http://www.evoketechnologies.com/blog/code-review-checklist-perform-effective-code-reviews/">Code Review Checklist – To Perform Effective Code Reviews</a>
 178 * <a href="https://www.codeproject.com/Articles/524235/Codeplusreviewplusguidelines">Code review guidelines</a>
 179 * <a href="https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md">C++ Core Guidelines</a>
 180 * <a href="https://doc.lagout.org/programmation/C/CPP101.pdf">C++ Coding Standards (Sutter & Andrescu)</a>
 181
 182 Beast thrives on code reviews and any sort of feedback from users and
 183 stakeholders about its interfaces. Even if you just have questions,
 184 asking them in the code review or in issues provides valuable information
 185 that can be used to improve the library - do not hesitate, no question
 186 is insignificant or unimportant!