Repository files navigation

Branch	Linux / Windows	Coverage	Documentation	Matrix
master
develop

• Introduction
• Appearances
• Description
• Requirements
• Git Branches
• Building
• Usage
• License
• Contact
• Contributing

Beast is a C++ header-only library serving as a foundation for writinginteroperable networking libraries by providinglow-level HTTP/1,WebSocket, and networking protocol vocabulary types and algorithmsusing the consistent asynchronous model of Boost.Asio.

This library is designed for:

• Symmetry: Algorithms are role-agnostic; build clients, servers, or both.

• Ease of Use: Boost.Asio users will immediately understand Beast.

• Flexibility: Users make the important decisions such as buffer orthread management.

• Performance: Build applications handling thousands of connections or more.

• Basis for Further Abstraction. Components are well-suited for building upon.

CppCon 2018	Bishop Fox 2018

CppCon 2017	CppCast 2017	CppCon 2016

This software is in its first official release. Interfacesmay change in response to user feedback. For recent changessee theCHANGELOG.

• Official Site
• Documentation (master branch)
• Autobahn|Testsuite WebSocket Results

This library is for programmers familiar with Boost.Asio. Userswho wish to use asynchronous interfaces should already know how tocreate concurrent network programs using callbacks or coroutines.

• C++11: Robust support for most language features.
• Boost: Boost.Asio and some other parts of Boost.
• OpenSSL: Required for using TLS/Secure sockets and examples/tests

When using Microsoft Visual C++, Visual Studio 2017 or later is required.

One of these components is required in order to build the tests and examples:

• Properly configured bjam/b2
• CMake 3.5.1 or later (Windows only)

Beast is header-only. To use it just add the necessary#include lineto your source files, like this:

#include<boost/beast.hpp>

If you use coroutines you'll need to link with the Boost.Coroutinelibrary. Please visit the Boost documentation for instructionson how to do this for your particular build system.

To use the latest official release of Beast, simply obtain the latestBoost distribution and follow the instructions for integrating itinto your development environment. If you wish to build the examplesand tests, or if you wish to preview upcoming changes and features,it is suggested to clone the "Boost superproject" and work with Beast"in-tree" (meaning, the libs/beast subdirectory of the superproject).

The official repository contains the following branches:

• master Thisholds the most recent snapshot with code that is known to be stable.

• develop Thisholds the most recent snapshot. It may contain unstable code.

Each of these branches requires a corresponding Boost branch andall of its subprojects. For example, if you wish to use themasterbranch version of Beast, you should clone the Boost superproject,switch to themaster branch in the superproject and acquireall the Boost libraries corresponding to that branch including Beast.

To clone the superproject locally, and switch into the main project'sdirectory use:

git clone --recursive https://github.com/boostorg/boost.gitcd boost

"bjam" is used to build Beast and the Boost libraries. On a non-Windowssystem use this command to build bjam:

./bootstrap.sh

From a Windows command line, build bjam using this command:

.\BOOTSTRAP.BAT

Building tests and examples requires OpenSSL installed. If OpenSSL is installedin a non-system location, you will need to copy theuser-config.jam file into your home directory and settheOPENSSL_ROOT environment variable to the path that contains an installationof OpenSSL.

If installed into a system directory, OpenSSL will be automatically found and used.

sudo apt install libssl-dev

Replacepath in the following code snippets with the path you installed vcpkgto. Examples assume a 32-bit build, if you build a 64-bit version replacex32-windows withx64-windows in the path.

• Usingvcpkg and CMD:

vcpkg install openssl --triplet x32-windowsSETOPENSSL_ROOT=path\installed\x32-windows

• Usingvcpkg and PowerShell:

vcpkg install openssl--triplet x32-windows$env:OPENSSL_ROOT="path\x32-windows"

• Usingvcpkg and bash:

vcpkg.exe install openssl --triplet x32-windowsexport OPENSSL_ROOT=path/x32-windows

Usingbrew:

brew install opensslexport OPENSSL_ROOT=$(brew --prefix openssl)# install bjam tool user specific configuration file to read OPENSSL_ROOT# see https://www.bfgroup.xyz/b2/manual/release/index.htmlcp ./libs/beast/tools/user-config.jam$HOME

Make sure the bjam tool (also called "b2") is available in the pathyour shell uses to find executables. The Beast project is located in"libs/beast" relative to the directory containing the Boot superproject.To build the Beast tests, examples, and documentation use these commands:

export PATH=$PWD:$PATHb2 -j2 libs/beast/test cxxstd=11      # bjam must be in your $PATHb2 -j2 libs/beast/example cxxstd=11   # "-j2" means use two processorsb2 libs/beast/doc                     # Doxygen and Saxon are required for this

Additional instructions for configuring, using, and building librariesin superproject may be found in theBoost Wiki.

CMake may be used to generate a very nice Visual Studio solution anda set of Visual Studio project files using these commands:

cmake -G "Visual Studio 17 2022" -A win32 -B bin -DCMAKE_TOOLCHAIN_FILE="C:/vcpkg/scripts/buildsystems/vcpkg.cmake" -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE="C:/boost/libs/beast/cmake/toolchains/msvc.cmake"cmake -G "Visual Studio 17 2022" -A x64 -B bin64 -DCMAKE_TOOLCHAIN_FILE="C:/vcpkg/scripts/buildsystems/vcpkg.cmake" -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE="C:/boost/libs/beast/cmake/toolchains/msvc.cmake"

The files in the repository are laid out thusly:

./    bin/            Create this to hold executables and project files    bin64/          Create this to hold 64-bit Windows executables and project files    doc/            Source code and scripts for the documentation    include/        Where the header files are located    example/        Self contained example programs    meta/           Metadata for Boost integration    test/           The unit tests for Beast    tools/          Scripts used for CI testing

These examples are complete, self-contained programs that you can buildand run yourself (they are in theexample directory).

https://www.boost.org/doc/libs/develop/libs/beast/doc/html/beast/quick_start.html

Distributed under the Boost Software License, Version 1.0.(See accompanying fileLICENSE_1_0.txt or copy athttps://www.boost.org/LICENSE_1_0.txt)

Please report issues or questions here:https://github.com/boostorg/beast/issues

If you would like to contribute to Beast and help us maintain highquality, consider performing code reviews on active pull requests.Any feedback from users and stakeholders, even simple questions abouthow things work or why they were done a certain way, carries valueand can be used to improve the library. Code review provides thesebenefits:

• Identify bugs
• Documentation proof-reading
• Adjust interfaces to suit use-cases
• Simplify code

You can look through the Closed pull requests to get an idea of howreviews are performed. To give a code review just sign in with yourGitHub account and then add comments to any open pull requests below,don't be shy!

https://github.com/boostorg/beast/pulls

Here are some resources to learn more aboutcode reviews:

• Top 10 Pull Request Review Mistakes
• Best Kept Secrets of Peer Code Review (pdf)
• 11 Best Practices for Peer Code Review (pdf)
• Code Review Checklist – To Perform Effective Code Reviews
• Code review guidelines
• C++ Core Guidelines
• C++ Coding Standards (Sutter & Alexandrescu)

Beast thrives on code reviews and any sort of feedback from users andstakeholders about its interfaces. Even if you just have questions,asking them in the code review or in issues provides valuable informationthat can be used to improve the library - do not hesitate, no questionis insignificant or unimportant!