Obtain And Build
Prerequisites
To use RESTinio you need to heve the following:
- Reasonably modern C++17 compiler;
- asio or Boost;
- nodejs/llhttp;
- fmtlib.
- expected-lite.
For building samples, benchmarks and tests:
- Catch2 v3.
- Optional: SObjectizer;
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 from releases section.
- Using vcpkg dependency manager.
- Using Conan dependency manager.
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:
[requires]
restinio/0.7.0
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
[requires]
restinio/0.7.0
[options]
restinio:asio=boost
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 theasio::asio
cmake-target is defined or that theasio_INCLUDE_DIRS
CMake variable is defined. On the level of the root cmake-fileasio
would be discovered usingfind_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 theBoost::headers
cmake-target is defined or that theBoost_INCLUDE_DIRS
cmake-variable is defined. On the level of the root cmake-fileboost
would be discovered usingfind_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 usingRESTINIO_LLHTTP_LIB_LINK_NAME
cmake-variable, by defaultllhttp
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-filellhttp
would be discovered usingfind_package()
cmake-function.local
- regarding targets expectations are the same as forfind
. 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 usingRESTINIO_FMT_LIB_LINK_NAME
cmake-variable, or RESTinio will setFMT_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
andfmt::fmt-header-only
) you can useRESTINIO_FMT_TARGET
cmake-variable. If it is undefinedfmt::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-filefmt
would be discovered usingfind_package()
cmake-function.local
- regarding targets expectations are the same as forfind
. 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-variablenonstd_expected-lite_INCLUDE_DIRS
ornonstd_INCLUDE_DIRS
is defined. On the level of the root cmake-fileexpected-lite
would be discovered usingfind_package()
cmake-function.local
- regarding targets expectations are the same as forfind
. 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 usefind_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 viaRESTINIO_SOBJECTIZER_LIB_LINK_NAME
.find
- RESTinio will usefind_package()
cmake-function to find SObjectizer installation. The target namesobjectizer::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
andASIO_HAS_STD_CHRONO
defines are necessary. AlsoASIO_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