Obtain And Build

Prerequisites

To use RESTinio it is necessary to have:

Reasonably modern C++14 compiler (VC++14.0 or above, GCC 5.4 or above, clang 3.8 or above);
asio 1.12.1 or above;
nodejs/http-parser 2.8.1;
fmtlib 5.2.1.
Optional: SObjectizer 5.5.22.1 or above;

For building samples, benchmarks and tests:

Mxx_ru 1.6.13 or above;
rapidjson 1.1.0;
json_dto 0.2.3 or above;
clara 1.1.5;
Catch2 2.4.2.

Obtaining

There are several ways of obtaining RESTinio.

Getting from repository. In this case external dependencies must be obtained with Mxx_ru externals tool.
Getting archive. Archive includes source code for all external dependencies.
Using vcpkg dependency manager.
Using Conan dependency manager.

Cloning of hg repository

RESTinio is hosted on mercurial bitbucket repository. So you need mercurial to be installed.

For mxxruexternals to work you need ruby with installed gem Mxx_ru. To get the dependencies with mxxruexternals you need the following additional packages to be installed: wget, tar, unzip, git.

While on Linux platform prepared for C++ development all of them most likely are already installed on windows it gets trickier. And there are 2 major options. The first one is to get restinio from an archive with all required sources in it. And the second is to use Cygwin or MinGW environments with above-mentioned packages installed.

Get repository:

hg clone https://bitbucket.org/sobjectizerteam/restinio-0.4

Get required external dependencies:

cd restinio-0.4
mxxruexternals

Getting archive

Choose the file from downloads page <https://bitbucket.org/sobjectizerteam/restinio-0.4/downloads/>.

wget https://bitbucket.org/sobjectizerteam/restinio-0.4/downloads/<ARCHIVE>
tar xjvf <ARCHIVE>
cd <UNPACKED_DIR>

MxxRu::externals recipe

For RESTinio itself:

MxxRu::arch_externals :restinio do |e|
  e.url 'https://bitbucket.org/sobjectizerteam/restinio-0.4/get/v.0.4.8.4.tar.bz2' # or another version.

  e.map_dir 'dev/restinio' => 'dev'

  # For building nodejs http-parser with cmake.
  e.map_file 'dev/nodejs/http_parser/CMakeLists.txt' => 'dev/nodejs/http_parser/*'
end

For dependencies:

MxxRu::arch_externals :asio do |e|
  e.url 'https://github.com/chriskohlhoff/asio/archive/asio-1-12-1.zip'

  e.map_dir 'asio/include' => 'dev/asio'
end

MxxRu::arch_externals :asio_mxxru do |e|
  e.url 'https://bitbucket.org/sobjectizerteam/asio_mxxru-1.1/get/1.1.2.tar.bz2'

  e.map_dir 'dev/asio_mxxru' => 'dev'
end

MxxRu::arch_externals :nodejs_http_parser do |e|
  e.url 'https://github.com/nodejs/http-parser/archive/v2.8.1.tar.gz'

  e.map_file 'http_parser.h' => 'dev/nodejs/http_parser/*'
  e.map_file 'http_parser.c' => 'dev/nodejs/http_parser/*'
end

MxxRu::arch_externals :nodejs_http_parser_mxxru do |e|
  e.url 'https://bitbucket.org/sobjectizerteam/nodejs_http_parser_mxxru-0.2/get/v.0.2.0.tar.bz2'

  e.map_dir 'dev/nodejs/http_parser_mxxru' => 'dev/nodejs'
end

MxxRu::arch_externals :fmt do |e|
  e.url 'https://github.com/fmtlib/fmt/archive/5.2.1.zip'

  e.map_dir 'include' => 'dev/fmt'
  e.map_dir 'src' => 'dev/fmt'
  e.map_dir 'support' => 'dev/fmt'
  e.map_file 'CMakeLists.txt' => 'dev/fmt/*'
  e.map_file 'README.rst' => 'dev/fmt/*'
  e.map_file 'ChangeLog.rst' => 'dev/fmt/*'
end

MxxRu::arch_externals :fmtlib_mxxru do |e|
  e.url 'https://bitbucket.org/sobjectizerteam/fmtlib_mxxru/get/fmt-5.0.0.tar.bz2'

  e.map_dir 'dev/fmt_mxxru' => 'dev'
end

For building samples, benches and tests:

MxxRu::arch_externals :so5 do |e|
  e.url 'https://github.com/eao197/so-5-5/archive/v5.5.23.zip'

  e.map_dir 'dev/so_5' => 'dev'
  e.map_dir 'dev/timertt' => 'dev'
end

MxxRu::arch_externals :rapidjson do |e|
  e.url 'https://github.com/miloyip/rapidjson/archive/v1.1.0.zip'

  e.map_dir 'include/rapidjson' => 'dev/rapidjson/include'
end

MxxRu::arch_externals :rapidjson_mxxru do |e|
  e.url 'https://bitbucket.org/sobjectizerteam/rapidjson_mxxru-1.0/get/v.1.0.0.tar.bz2'

  e.map_dir 'dev/rapidjson_mxxru' => 'dev'
end

MxxRu::arch_externals :json_dto do |e|
  e.url 'https://bitbucket.org/sobjectizerteam/json_dto-0.2/downloads/json_dto-0.2.6-full.zip'

  e.map_dir 'dev/json_dto' => 'dev'
end

MxxRu::arch_externals :clara do |e|
  e.url 'https://github.com/catchorg/Clara/archive/v1.1.5.tar.gz'

  e.map_file 'single_include/clara.hpp' => 'dev/clara/*'
end

MxxRu::arch_externals :catch do |e|
  e.url 'https://github.com/catchorg/Catch2/archive/v2.4.2.tar.gz'

  e.map_dir 'single_include/catch2' => 'dev'
end

Vcpkg

Since v.0.4.5.1. RESTinio is available with vcpkg:

vcpkg install restinio

Simple as that, now you can use it within your cmake-based project or use it in Visual Studio.

Using with CMake:

cmake_minimum_required(VERSION 3.8.0)
project (helloworld)
add_executable(helloworld helloworld.cpp)

# RESTinio dependencies:
# 1. ASIO or Boost::ASIO (goes as headers, vcpkg knows where)
# 2. HTTP parser
find_package(unofficial-http-parser REQUIRED)
# 3. fmtlib
find_package(fmt REQUIRED)
# RESTinio itself
find_package(restinio REQUIRED)

# Make your project dependent on restinio,
# and let cmake deal with all the headers paths and linked libs.
target_link_libraries(helloworld PRIVATE restinio::restinio)

Conan

Since Nov 2018 RESTinio is available via Conan dependency manager. Conan’s package for RESTinio can be found here.

Installing Via Conan

To use RESTinio via Conan it is necessary to do the following steps:

Add the corresponding remote to your conan:

conan remote add stiffstream https://api.bintray.com/conan/stiffstream/public

It can be also necessary to add public-conan remote:

conan remote add public-conan https://api.bintray.com/conan/bincrafters/public-conan

Add RESTinio to conanfile.txt of your project:

[requires]
restinio/0.4.8.3@stiffstream/testing
RESTinio will use standalone version of Asio by default.

It you want to use RESTinio with Boost.Asio you have to:

Add Boost to your conanfile.txt:

[requires]
restinio/0.4.8.3@stiffstream/testing
boost/1.68.0@conan/stable

Specify boost_libs option for RESTinio. This option should have static or shared. If you use static value then you should specify shared=False option for Boost libraries:

[options]
restinio:boost_libs=static
boost:shared=False

If you use shared value for restinio:boost_libs then you should specify shared=True option for Boost libraries:

[options]
restinio:boost_libs=shared
boost:shared=True

Install dependencies for your project:

conan install SOME_PATH --build=missing

Adding RESTinio To Your CMakeLists.txt

Please note that SObjectizer should be added to your CMakeLists.txt via find_package command:

include(${CMAKE_BINARY_DIR}/conanbuildinfo.cmake)
conan_basic_setup()

find_package(restinio CONFIG REQUIRED)
...
target_link_libraries(your_target restinio::restinio)
target_link_libraries(your_target ${CONAN_LIBS})

Examples

Some simple examples of using RESTinio via Conan can be found in the following repositories:

Build

While RESTinio is a header-only library, samples, tests and benches require a build.

CMake

To build RESTinio with examples and tests run the following commands:

hg clone https://bitbucket.org/sobjectizerteam/restinio-0.4
cd restinio-0.4
mxxruexternals
cd dev
mkdir cmake_build
cd cmake_build
cmake -DCMAKE_INSTALL_PREFIX=target -DCMAKE_BUILD_TYPE=Release ..
cmake --build . --config Release --target install

Or, if getting sources from archive (<ARCHIVE>):

wget https://bitbucket.org/sobjectizerteam/restinio-0.4/downloads/<ARCHIVE>
tar xjvf <ARCHIVE>
cd <UNPACKED_DIR>/dev
mkdir cmake_build
cd cmake_build
cmake -DCMAKE_INSTALL_PREFIX=target -DCMAKE_BUILD_TYPE=Release ..
cmake --build . --config Release --target install

Resolving dependencies

RESTinio has a mandatory set of dependencies: ASIO, http-parser, fmt. Others are optional and are necessary for enabling enhanced features of RESTinio (OpenSSL, ZLIB, PCRE, PCRE2, Boost.Regex).

All optional dependencies are included with find_package() cmake function. And only if the library is found tests and samples which depends on it are built.

For mandatory dependencies, a different approach is used. RESTinio includes ASIO, http-parser and fmt as a part of the sources (coming with archive). By default cmake build uses local sources. For ASIO a necessary include path and macro definitions are provided for building restinio cmake-target. For fmt and http-parser a paths to local sources are included with add_subdirectory() That’s makes their targets available: fmt::fmt-header-only, unofficial::http_parser::http_parser (such a hame for the target is because the upstream version of the library doesn’t support cmake and its wrapper cannot be considered official and that is stated by target name).

But for including mandatory dependencies we can also use find_package() (and in general it is a more canonical way for cmake). To enable this way of including dependencies the following cmake option must be defined: RESTINIO_FIND_DEPS. Usage example (assuming build from the archive):

cmake -DRESTINIO_FIND_DEPS=ON -DCMAKE_INSTALL_PREFIX=<PATH_TO_LOCAL_LIBS> \
-DCMAKE_PREFIX_PATH=<PATH_TO_LOCAL_LIBS> -DCMAKE_BUILD_TYPE=Release ..

If it is planned to install RESTinio it is better to build it with -DRESTINIO_FIND_DEPS=ON so that RESTinio dependencies are propagated nicely to targets which depend on RESTinio. In that case, RESTinio dependencies are included as cmake target properties and are propagated to dependent targets.

Include RESTinio in your project

Canonical way

First, build and install RESTinio dependencies. Then build and install RESTinio itself with -DRESTINIO_FIND_DEPS=ON and passing CMAKE_PREFIX_PATH to locate dependencies. Then use the directory with installed RESTinio for using with your project.

find_package(restinio REQUIRED)

 # Make your project dependent on restinio,
 # and let cmake deal with all the headers paths and linked libs.
 target_link_libraries(MyProject PRIVATE restinio::restinio)

Copy RESTinio to your build-tree

One can simply copy a directory with RESTinio (dev/restinio where all.hpp is located) into own build-tree. And include RESTinio with add_subdirectory() (RESTINIO_FIND_DEPS option can be set to either ON or OFF).

Mxx_ru

Compiling with Mxx_ru:

hg clone https://bitbucket.org/sobjectizerteam/restinio-0.4
cd restinio-0.4
mxxruexternals
cd dev
ruby build.rb

For release or debug builds use the following commands:

ruby build.rb --mxx-cpp-release
ruby build.rb --mxx-cpp-debug

NOTE. It might be necessary to set up MXX_RU_CPP_TOOLSET environment variable, see Mxx_ru documentation for further details.

Dependencies default settings

External libraries used by RESTinio have the following default settings:

A standalone version of asio is used and a chrono library is used, so ASIO_STANDALONE and ASIO_HAS_STD_CHRONO defines are necessary. Also ASIO_DISABLE_STD_STRING_VIEW is defined because it is a C++17 feature and not all compilers support it yet;
a less strict version of nodejs/http-parser is used, so the following definition HTTP_PARSER_STRICT=0 is applied;
fmtlib is used as a header-only library, hence a FMT_HEADER_ONLY define is necessary;
for RapidJSON two definitions are necessary: RAPIDJSON_HAS_STDSTRING and RAPIDJSON_HAS_CXX11_RVALUE_REFS.

Notes on building with Boost::ASIO

RESTinio supports Boost::ASIO since Boost version 1.66. Earlier versions come with ASIO API that is not supported. Boost::ASIO depends on Boost::System, and it is a compiled library. And this circumstance involves some difficulties.

If you have any suggestions on how to integrate with both ASIO versions should be done to minimize maintaining and building efforts, please, provide us with your feedback.

CMake

To use RESTinio with Boost::ASIO in your project define RESTINIO_USE_BOOST_ASIO variable with value shared or static.

cmake ... -DRESTINIO_USE_BOOST_ASIO=shared ...

An example for building tests, samples and benchmarks with cmake:

wget https://bitbucket.org/sobjectizerteam/restinio-0.4/downloads/<ARCHIVE>
tar xjvf <ARCHIVE>
cd <UNPACKED_DIR>/dev
mkdir cmake_build
cd cmake_build
cmake -DCMAKE_INSTALL_PREFIX=target -DCMAKE_BUILD_TYPE=Release -DRESTINIO_USE_BOOST_ASIO=shared -DBOOST_ROOT=~/boost/boost_1_66_0 ..
cmake --build . --config Release --target install

Note: On Windows the latest cmake has an issue <https://gitlab.kitware.com/cmake/cmake/issues/17575> working with Boost 1.66. At the moment of writing this doc CMake 3.10.2 still doesn’t get the names right.

Mxx_ru

First of all, an environment variable RESTINIO_USE_BOOST_ASIO must be defined. It must be either RESTINIO_USE_BOOST_ASIO=shared or RESTINIO_USE_BOOST_ASIO=static.

On linux

Make sure the right version of Boost is in your include path directories. E.g. listed in CPLUS_INCLUDE_PATH environment variable. Note: there might be an issue with boost-dev package that might provide earlier versions of Boost (for example 1.58 on Ubuntu 16.04). In this case, even adding the right Boost version to include directories via -I<path> option won’t work because system include directories will be considered first.
Make sure the right version of Boost is in your library path directories. E.g. listed in LIBRARY_PATH environment variable. Note: there might be an issue with boost-dev package that might provide earlier versions of Boost (for example 1.58 on Ubuntu 16.04). In this case, even adding the right Boost version to lib directories via -L<path> option won’t work because system include directories will be considered first.

If mentioned conditions are fulfilled tests, samples and benchmarks are built as usual.

Sample build on linux with Boost (Boost installed to ~/boost/boost_1_66_0):

export CPLUS_INCLUDE_PATH=$CPLUS_INCLUDE_PATH:~/boost/boost_1_66_0/include
export LIBRARY_PATH=$LIBRARY_PATH:~/boost/boost_1_66_0/lib
export RESTINIO_USE_BOOST_ASIO=static
ruby build.rb --mxx-cpp-release

On Windows

On Windows Boost has a complicated logic for naming library files. But Mxx_ru scripts try its best to deal with it. It is considered that Boost is compiled without changing the convention for resulting binaries names (like precompiled binaries for msvc or reasonable default builds for MinGW).

Depending on the toolset there are the following note:

MSVC: Boost includes and libraries can be deduced from BOOSTROOT``(or ``BOOST_ROOT) environment variable or otherwise mxx-scripts consider Boost headers and libraries are listed in INCLUDE and LIB directories respectively.
MinGW (gcc): Boost headers and libraries are considered to be set as include/libs for a given build environment.

Sample build on windows with MSVC (Boost installed to C:\boost\boost_1_66_0):

set BOOST_TROOT=C:\boost\boost_1_66_0
set RESTINIO_USE_BOOST_ASIO=static
ruby build.rb --mxx-cpp-release

or using system include/libs directories:

set INCLUDE=%INCLUDE%;C:\boost\boost_1_66_0
set LIB=%LIB%;C:\boost\boost_1_66_0\lib64-msvc-14.1
REM Add dll dir to path.
set PATH=%LIB%;C:\boost\boost_1_66_0\lib64-msvc-14.1
set RESTINIO_USE_BOOST_ASIO=shared
ruby build.rb --mxx-cpp-release

Obtain And Build

Prerequisites

Obtaining

Cloning of hg repository

Getting archive

MxxRu::externals recipe

Vcpkg

Conan

Installing Via Conan

Adding RESTinio To Your CMakeLists.txt

Examples

Build

CMake

Resolving dependencies

Include RESTinio in your project

Canonical way

Copy RESTinio to your build-tree

Mxx_ru

Dependencies default settings

Notes on building with Boost::ASIO

CMake

Mxx_ru

Table Of Contents

Search