From 2dde0ac95049a541f7fba654e3aeb6e239c16217 Mon Sep 17 00:00:00 2001 From: The-EDev Date: Thu, 3 Jun 2021 17:12:48 +0300 Subject: [PATCH] updated documentation to fix a few mistakes, clear up a few points, and added compression guide --- docs/getting_started/setup.md | 47 ++++++++++++++++++++++++----------- docs/guides/compression.md | 18 ++++++++++++++ docs/guides/ssl.md | 4 ++- mkdocs.yml | 1 + 4 files changed, 55 insertions(+), 15 deletions(-) create mode 100644 docs/guides/compression.md diff --git a/docs/getting_started/setup.md b/docs/getting_started/setup.md index a7013ff89..8b6eb47f6 100644 --- a/docs/getting_started/setup.md +++ b/docs/getting_started/setup.md @@ -3,21 +3,36 @@ This page explains how to set Crow up for use with your project. ##Requirements - C++ compiler with C++14 support. - - Continuous Testing on g++-9.3 and clang-7.0, AMD64 (x86_64) and Arm64 v8 + - Crow's CI uses g++-9.3 and clang-7.0 running on AMD64 (x86_64) and ARM64v8 - boost library (1.70 or later). - - (optional) CMake and Python3 to build tests and/or examples. - - (optional) Linking with jemalloc/tcmalloc is recommended for speed. + - **(optional)** ZLib for HTTP Compression. + - **(optional)** CMake and Python3 to build tests and/or examples. + - **(optional)** Linking with jemalloc/tcmalloc is recommended for speed. +!!!note + + While using Boost 1.70 or later is recommended, it may be possible to compile a Crow application with version 1.64 +

##Installing Requirements +!!! note + + The Linux requirements are for developing and compiling a Crow application. Running a built application requires the actual libraries rather than just the development headers. + ###Ubuntu -`sudo apt-get install libboost-all-dev` +`sudo apt-get install build-essential libboost-all-dev` + +###Non Debian based GNU/Linux +Use your package manager to install the following: + - GCC and G++ (or Clang and Clang++) + - Boost Development headers (sometimes part of the Boost package itself) + ###OSX `brew install boost` ###Windows -Download boost from [here](https://www.boost.org/) and install it +Microsoft Visual Studio 2019 (older versions not tested) ##Downloading Either run `git clone https://github.com/crowcpp/crow.git` or download `crow_all.h` from the releases section. You can also download a zip of the project on github. @@ -29,7 +44,7 @@ Either run `git clone https://github.com/crowcpp/crow.git` or download `crow_all

##Single header file -If you've downloaded `crow_all.h`, you can skip to step 4. +If you've downloaded `crow_all.h`, you can skip to step **4**. 1. Make sure you have python 3 installed. 2. Open a terminal (or `cmd.exe`) instance in `/path/to/crow/scripts`. @@ -44,16 +59,18 @@ If you've downloaded `crow_all.h`, you can skip to step 4. To build a crow Project, do the following: ###GCC (G++) - - Release: `g++ main.cpp -lpthread -lboost_system -lz`. - - Debug: `g++ main.cpp -ggdb -lpthread -lboost_system -lz -D CROW_ENABLE_DEBUG`. - - SSL: `g++ main.cpp -lssl -lcrypto -lpthread -lboost_system -lz -D CROW_ENABLE_SSL`. + - Release: `g++ main.cpp -lpthread -lboost_system`. + - Debug: `g++ main.cpp -ggdb -lpthread -lboost_system -DCROW_ENABLE_DEBUG`. + - SSL: `g++ main.cpp -lssl -lcrypto -lpthread -lboost_system -DCROW_ENABLE_SSL`. ###Clang - - Release: `clang++ main.cpp -lpthread -lboost_system -lz`. - - Debug: `clang++ main.cpp -g -lpthread -lboost_system -lz -DCROW_ENABLE_DEBUG`. - - SSL: `clang++ main.cpp -lssl -lcrypto -lpthread -lboost_system -lz -DCROW_ENABLE_SSL`. + - Release: `clang++ main.cpp -lpthread -lboost_system`. + - Debug: `clang++ main.cpp -g -lpthread -lboost_system -DCROW_ENABLE_DEBUG`. + - SSL: `clang++ main.cpp -lssl -lcrypto -lpthread -lboost_system -DCROW_ENABLE_SSL`. + +###Microsoft Visual Studio 2019 +The following guide will use `example_with_all.cpp` as the Crow application for demonstration purposes. -###Microsoft Visual Studio 2019 (`example_with_all.cpp`) 1. Generate `crow_all.h` following [Single header file](#single-header-file). 2. `git clone https://github.com/microsoft/vcpkg.git` 3. `.\vcpkg\bootstrap-vcpkg.bat` @@ -97,7 +114,9 @@ set(PROJECT_INCLUDE_DIR ${PROJECT_SOURCE_DIR}/include) include_directories("${PROJECT_INCLUDE_DIR}") ``` -**Note**: The last 2 lines are unnecessary if you're using `crow_all.h`. +!!!note + + The last 2 lines are unnecessary if you're using `crow_all.h`. ##Building Crow tests and examples Out-of-source build with CMake is recommended. diff --git a/docs/guides/compression.md b/docs/guides/compression.md new file mode 100644 index 000000000..89b8e80de --- /dev/null +++ b/docs/guides/compression.md @@ -0,0 +1,18 @@ +Crow supports Zlib compression using Gzip or Deflate algorithms. + +## HTTP Compression +HTTP compression is by default disabled in crow. Do the following to enable it:
+1. Add `#!cpp #define CROW_ENABLE_COMPRESSION` to the top of your main source file. +2. Call `#!cpp use_compression(crow::compression::algorithm)` on your crow app. +3. When compiling your application, make sure that ZLIB is included as a dependency. Either through `-lz` argument or `find_package(ZLIB)` in CMake. + +!!! note + + step 3 is not needed for MSVC since `vcpckg.json` already includes zlib as a dependency by default + +For the compression algorim you can use `crow::compression::algorithm::DEFLATE` or `crow::compression::algorithm::GZIP`.
+And now your HTTP responses will be compressed. + +## Websocket Compression +Crow currently does not support Websocket compression.
+Feel free to discuss the subject with us on Github if you're feeling adventurous and want to try to implement it. We appreciate all the help. diff --git a/docs/guides/ssl.md b/docs/guides/ssl.md index ac3017b0e..6c2828d42 100644 --- a/docs/guides/ssl.md +++ b/docs/guides/ssl.md @@ -7,4 +7,6 @@ To enable SSL, first your application needs to define either a `.crt` and `.key` You can also set your own SSL context (by using `boost::asio::ssl::context ctx`) and then applying it via the `#!cpp app.ssl(ctx)` method.

-**IMPORTANT NOTICE**: If you plan on using a proxy like Nginx or Apache2, **DO NOT** use SSL in crow, instead define it in your proxy instead and keep the connection between the proxy and Crow non-SSL. \ No newline at end of file +!!! warning + + If you plan on using a proxy like Nginx or Apache2, **DO NOT** use SSL in crow, instead define it in your proxy and keep the connection between the proxy and Crow non-SSL. diff --git a/mkdocs.yml b/mkdocs.yml index 4f484085d..d3507a839 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -41,6 +41,7 @@ nav: - Middleware: guides/middleware.md - SSL: guides/ssl.md - Static Files: guides/static.md + - Compression: guides/compression.md - Websockets: guides/websockets.md - Writing Tests: guides/testing.md - Server setup: