Obtain And Build

Prerequisites

To use RESTinio you need to heve the following:

For building samples, benchmarks and tests:

Obtaining

There are several ways of obtaining RESTinio.

Cloning of Git repository

RESTinio is hosted on GitHub repository. So you need git 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:

git clone https://github.com/stiffstream/restinio

Get required external dependencies:

cd restinio
mxxruexternals

Getting archive

Choose the file from releases page. For example:

wget https://github.com/Stiffstream/restinio/releases/download/v.0.7.0/restinio-0.7.0.tar.bz2
tar xjvf <ARCHIVE>
cd <UNPACKED_DIR>

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 (or other IDE).

Using with CMake:

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

# 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: in public registry - CCI. 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 RESTinio to conanfile.txt of your project:

conanfile.txt
[requires]
restinio/0.7.0
conanfile.py
def requirements(self):
    self.requires("restinio/0.7.0")

RESTinio will use standalone version of Asio by default. To make RESTinio use Boost.Asio you should use package option restinio:asio=boost

conanfile.txt
[requires]
restinio/0.7.0

[options]
restinio:asio=boost
conanfile.py
def requirements(self):
    self.requires("restinio/0.7.0")
    self.options["restinio"].asio = "boost"

For further options, please refer to restinio conan package documentation.

Install dependencies for your project:

conan install -s build_type=Release -if SOME_PATH --build=missing .

Adding RESTinio To Your CMakeLists.txt

There is a simple CMakeLists.txt file that shows how RESTinio can be used via Conan in your project file:

cmake_minimum_required(VERSION 2.8)

project(your_project)

include(${CMAKE_BINARY_DIR}/conanbuildinfo.cmake)

# Provide all necessary depndencies as cmake-targets.
conan_basic_setup()

add_executable(your_target your_main_file.cpp)

target_link_libraries(your_target restinio::restinio)
set_property(TARGET your_target PROPERTY CXX_STANDARD 17)

Build

While RESTinio is a header-only library, it depends on llhttp library, that has to be compiled. The samples, tests and benchmarks require a build too.

CMake

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

git clone https://github.com/stiffstream/restinio
cd restinio
mxxruexternals
cd dev
cmake -Bcmake_build -DCMAKE_BUILD_TYPE=Release .
cmake --build cmake_build --config Release -j 4
# For linux it could be:
# cmake --build cmake_build -j 4

Or, if getting sources from archive (version 0.7.0 is used just for example):

wget https://github.com/Stiffstream/restinio/releases/download/v.0.7.0/restinio-0.7.0.tar.bz2
tar xjvf restinio-0.7.0.tar.bz2
cd restinio-0.7.0/dev
cmake -Bcmake_build -DCMAKE_BUILD_TYPE=Release .
cmake --build cmake_build --config Release -j 4

Resolving dependencies

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

All optional dependencies are included with find_package() cmake function in the root CMakeLists.txt. For optional dependencies if the library is found tests and samples which depends on it are included into a build (except SObjectizer whilch is obtained via Mxx_ru externals).

Mandatory dependencies are handled in a different approach. RESTinio includes ASIO, nodejs/llhttp, fmt, and expected-lite as part of the sources (you may think of it as git-submodules), When using CMake to build, it will use these local sources by default. For standalone ASIO, a necessary CMake find-module is provided in dev/cmake/module/FindAsio.cmake. This find-module creates the target asio::asio, which aligns with the naming conventions used by package managers. For fmt and nodejs/llhttp, paths to local sources are included using the add_subdirectory() command. This inclusion makes their targets available as fmt::fmt-header-only and llhttp::llhttp.

Since v.0.7.0 cmake-scripts for the project were refactored to comply with modern CMake practice and to allow a better integration of restinio as a dependency in cases no package manager (such as Conan or Vcpkg) is used and RESTinio comes as a submodule or in any other way that involves downloading a tarball of sources and building RESTinio as part of a CMake-based project.

Currently all essential decisions regarding dependencies are made in a root-cmake file which is not intended to be included with add_subdirectory() when RESTinio is used. In such scenarios one should use add_subdirectory(<restinio_dir>/dev/restionio).

To adjust the way dependencies are defined for restinio::restinio cmake-target you can utilize the following CMake options and variables:

  • RESTINIO_EXPLICIT_CPPSTD. Allows explicit setting of the C++ standard for the RESTinio target. Possible values: [17, 20, 23].

  • RESTINIO_ASIO_SOURCE. Specifies whether RESTinio should use standalone ASIO or Boost ASIO. Possible values: ["standalone", "boost"].

    Default: "standalone".

  • RESTINIO_DEP_STANDALONE_ASIO. Possible values: [system, find].

    Default: find.

    • system - RESTinio assumes that ASIO is available through system headers.
    • find - RESTinio expects either that the asio::asio cmake-target is defined or that the asio_INCLUDE_DIRS CMake variable is defined. On the level of the root cmake-file asio would be discovered using find_package() cmake-function.
  • RESTINIO_DEP_BOOST_ASIO. Possible values: [system, find]. Default: find.

    • system - RESTinio assumes that Boost ASIO is available through system headers.
    • find - RESTinio expects either that the Boost::headers cmake-target is defined or that the Boost_INCLUDE_DIRS cmake-variable is defined. On the level of the root cmake-file boost would be discovered using find_package() cmake-function.
  • RESTINIO_DEP_LLHTTP. Possible values: [system, find, local].

    Default: local.

    • system - RESTinio assumes nodejs/llhttp is available through system headers. You can adjust the library name to link with using RESTINIO_LLHTTP_LIB_LINK_NAME cmake-variable, by default llhttp name is used.
    • find - RESTinio expects llhttp cmake-target to be defined using one of the following names: [llhttp::llhttp, llhttp::llhttp_static, llhttp::llhttp_dynamic] (that is because names vary in differenct package managers). On the level of the root cmake-file llhttp would be discovered using find_package() cmake-function.
    • local - regarding targets expectations are the same as for find. The difference is on the level of the root cmake-file: a local copy of llhttp sources would be used (add_subdirectory()) to build it as a part of RESTinio project.
  • RESTINIO_DEP_FMT. Possible values: [system, find, local].

    Default: local.

    • system - RESTinio assumes FMTLIB is available through system headers. You can set the library name to link with using RESTINIO_FMT_LIB_LINK_NAME cmake-variable, or RESTinio will set FMT_HEADER_ONLY=1 for its target by default.
    • find. To handle possible names for fmt cmake-target (fmt’s native cmake-file already declares 2 legit target names: fmt::fmt and fmt::fmt-header-only) you can use RESTINIO_FMT_TARGET cmake-variable. If it is undefined fmt::fmt target name would be used. And the eventual name is expected by RESTinio to be defined as cmake-target. On the level of the root cmake-file fmt would be discovered using find_package() cmake-function.
    • local - regarding targets expectations are the same as for find. The difference is on the level of the root cmake-file: a local copy of FMTLIB sources would be used (add_subdirectory()) to build it as a part of RESTinio project.
  • RESTINIO_DEP_EXPECTED_LITE. Possible values: [system, find, local].

    Default: local.

    • system - RESTinio assumes nonstd::expected is available through system headers.
    • find - RESTinio expects that either nonstd::expected cmake-target is defined using one of the following names: [expected-lite::expected-lite, nonstd::expected-lite] (that is because names vary in differenct package managers) or cmake-variable nonstd_expected-lite_INCLUDE_DIRS or nonstd_INCLUDE_DIRS is defined. On the level of the root cmake-file expected-lite would be discovered using find_package() cmake-function.
    • local - regarding targets expectations are the same as for find. The difference is on the level of the root cmake-file: a local copy of expected-lite sources would be used (add_subdirectory()) to build it as a part of RESTinio project.
  • RESTINIO_DEP_CATCH2. Possible values: [find, local].

    NOTE: this option is available since v.0.7.2.

    Default: local.

    • find - RESTinio will use find_package() cmake-function to find Catch2 installation.
    • local - a local copy of Catch2 sources would be used (add_subdirectory()) to build it as a part of RESTinio project.
  • RESTINIO_DEP_SOBJECTIZER. Possible values: [system, find, local].

    NOTE: this option is available since v.0.7.2.

    Default: local.

    • system - RESTinio assumes SObjectizer is available through system headers and libraries. The name of SObjectizer target has to be specified explicitly via RESTINIO_SOBJECTIZER_LIB_LINK_NAME.
    • find - RESTinio will use find_package() cmake-function to find SObjectizer installation. The target name sobjectizer::StaticLib will be used for linking to SObjectizer’s static library.
    • local - a local copy of SObjectizer sources would be used (add_subdirectory()) to build it as a part of RESTinio project.

When building RESTinio from sources, there is one optional dependency that is not propagated through the restinio::restinio target directly. This dependency is on SObjectizer, which allows for building additional tests, examples, and benchmarks. If RESTINIO_WITH_SOBJECTIZER option is enabled (and it is enabled by default), RESTinio will consider building tests, examples, and benchmarks that have dependencies on SObjectizer.

Include RESTinio in your project

Copy RESTinio to your build-tree (git-submodule)

When using RESTinio as a dependency in a project, you have several options that revolve around having the RESTinio sources integrated into your project source’s tree:

  • Copy the directory containing RESTinio (found at dev/restinio, where core.hpp is located) into your project’s build tree.
  • Use Git submodules to incorporate the RESTinio source into your project.
  • Employ any other approach that involves having RESTinio as a part of your project’s source tree.

Once integrated, you can easily incorporate RESTinio into your CMake-based project using the add_subdirectory(...) command. It’s important to note that you should include the restinio directory itself, not the root cmake-file of the RESTinio project:

# WRONG:
add_subdirectory(<restinio-submodule-dir>/dev)

# CORRECT:
add_subdirectory(<restinio-submodule-dir>/dev/restinio)

To fine tune the way RESTinio gets to know about its own dependencies, please, check Resolving dependencies. it allows to adjust the definition of restinio::restinio cmake-target that work for your project.

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;
  • fmtlib is used as a header-only library, hence a FMT_HEADER_ONLY define is necessary;

Notes on building with Boost::ASIO

RESTinio supports Boost::ASIO since Boost version 1.74. Earlier versions of Boost.ASIO may or may not work.

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

wget https://github.com/Stiffstream/restinio/releases/<ARCHIVE>
tar xjvf <ARCHIVE>
cd <UNPACKED_DIR>/dev

# Using local Boost:
cmake -Bcmake_build \
   -DCMAKE_BUILD_TYPE=Release \
   -DRESTINIO_EXPLICIT_CPPSTD=20 \
   -DRESTINIO_ASIO_SOURCE=boost \
   -DBOOST_ROOT=~/boost/boost_1_83_0 \
   ..

# You can also set:
# -DRESTINIO_DEP_BOOST_ASIO=find
# But since it is a default option this is omitted
# in the above sample command.


# Using system package (Ubuntu 22.04 boost1.74):
cmake -Bcmake_build \
   -DCMAKE_BUILD_TYPE=Release \
   -DRESTINIO_EXPLICIT_CPPSTD=17 \
   -DRESTINIO_ASIO_SOURCE=boost \
   -DRESTINIO_DEP_BOOST_ASIO=system \
   ..

# Build and test:
cmake --build cmake_build -j 8
ctest -T test --test-dir cmake_build