The following CMake options are used by userver:
| Option | Description | Default |
|---|---|---|
| USERVER_FEATURE_CORE | Provide a core library with coroutines, otherwise build only userver-universal | ON |
| USERVER_FEATURE_MONGODB | Provide asynchronous driver for MongoDB | ${USERVER_IS_THE_ROOT_PROJECT} AND x86* AND NOT *BSD |
| USERVER_FEATURE_POSTGRESQL | Provide asynchronous driver for PostgreSQL | ${USERVER_IS_THE_ROOT_PROJECT} |
| USERVER_FEATURE_REDIS | Provide asynchronous driver for Redis | ${USERVER_IS_THE_ROOT_PROJECT} |
| USERVER_FEATURE_CLICKHOUSE | Provide asynchronous driver for ClickHouse | ${USERVER_IS_THE_ROOT_PROJECT} AND x86* |
| USERVER_FEATURE_GRPC | Provide asynchronous driver for gRPC | ${USERVER_IS_THE_ROOT_PROJECT} |
| USERVER_FEATURE_KAFKA | Provide asynchronous driver for Apache Kafka | ${USERVER_IS_THE_ROOT_PROJECT} |
| USERVER_FEATURE_RABBITMQ | Provide asynchronous driver for RabbitMQ (AMQP 0-9-1) | ${USERVER_IS_THE_ROOT_PROJECT} |
| USERVER_FEATURE_MYSQL | Provide asynchronous driver for MySQL/MariaDB | ${USERVER_IS_THE_ROOT_PROJECT} |
| USERVER_FEATURE_ROCKS | Provide asynchronous driver for RocksDB | ${USERVER_IS_THE_ROOT_PROJECT} |
| USERVER_FEATURE_YDB | Provide asynchronous driver for YDB | ${USERVER_IS_THE_ROOT_PROJECT} AND C++ standard >= 20 |
| USERVER_FEATURE_UTEST | Provide 'utest' and 'ubench' for unit testing and benchmarking coroutines | ${USERVER_FEATURE_CORE} |
| USERVER_FEATURE_CRYPTOPP_BLAKE2 | Provide wrappers for blake2 algorithms of crypto++ | ON |
| USERVER_FEATURE_PATCH_LIBPQ | Apply patches to the libpq (add portals support), requires libpq.a | ON |
| USERVER_FEATURE_CRYPTOPP_BASE64_URL | Provide wrappers for Base64 URL decoding and encoding algorithms of crypto++ | ON |
| USERVER_FEATURE_REDIS_HI_MALLOC | Provide a hi_malloc(unsigned long) issue workaround | OFF |
| USERVER_FEATURE_REDIS_TLS | SSL/TLS support for Redis driver | OFF |
| USERVER_FEATURE_STACKTRACE | Allow capturing stacktraces using boost::stacktrace | OFF if platform is not *BSD; ON otherwise |
| USERVER_FEATURE_JEMALLOC | Use jemalloc memory allocator | ON |
| USERVER_FEATURE_DWCAS | Require double-width compare-and-swap | ON |
| USERVER_FEATURE_TESTSUITE | Enable functional tests via testsuite | ON |
| USERVER_FEATURE_GRPC_CHANNELZ | Enable Channelz for gRPC | ON for "sufficiently new" gRPC versions |
| USERVER_CHECK_PACKAGE_VERSIONS | Check package versions | ON |
| USERVER_SANITIZE | Build with sanitizers support, allows combination of values via 'val1 val2' | '' |
| USERVER_SANITIZE_BLACKLIST | Path to file that is passed to the -fsanitize-blacklist option | '' |
| USERVER_USE_LD | Linker to use, e.g. 'gold' or 'lld' | '' |
| USERVER_LTO | Use link time optimizations | OFF |
| USERVER_LTO_CACHE | Use LTO cache if present, disable for benchmarking build times | ON |
| USERVER_LTO_CACHE_DIR | LTO cache directory | ${CMAKE_CURRENT_BINARY_DIR}/.ltocache |
| USERVER_LTO_CACHE_SIZE_MB | LTO cache size limit in MB | 6000 |
| USERVER_USE_CCACHE | Use ccache if present, disable for benchmarking build times | ON |
| USERVER_COMPILATION_TIME_TRACE | Generate Clang compilation time trace | OFF |
| USERVER_NO_WERROR | Do not treat warnings as errors | ON |
| USERVER_PYTHON_PATH | Path to the python3 binary for use in testsuite tests | python3 |
| USERVER_FEATURE_ERASE_LOG_WITH_LEVEL | Logs of this and below levels are removed from binary. Possible values: trace, info, debug, warning, error | OFF |
| USERVER_DOWNLOAD_PACKAGES | Download missing third party packages and use the downloaded versions | ON |
| USERVER_PIP_USE_SYSTEM_PACKAGES | Use system python packages inside venv | OFF |
| USERVER_PIP_OPTIONS | Options for all pip calls | '' |
| USERVER_DOWNLOAD_PACKAGE_CARES | Download and setup c-ares if no c-ares of matching version was found | ${USERVER_DOWNLOAD_PACKAGES} |
| USERVER_DOWNLOAD_PACKAGE_CCTZ | Download and setup cctz if no cctz of matching version was found | ${USERVER_DOWNLOAD_PACKAGES} |
| USERVER_DOWNLOAD_PACKAGE_CLICKHOUSECPP | Download and setup clickhouse-cpp | ${USERVER_DOWNLOAD_PACKAGES} |
| USERVER_DOWNLOAD_PACKAGE_CRYPTOPP | Download and setup CryptoPP if no CryptoPP of matching version was found | ${USERVER_DOWNLOAD_PACKAGES} |
| USERVER_DOWNLOAD_PACKAGE_CURL | Download and setup libcurl if no libcurl of matching version was found | ${USERVER_DOWNLOAD_PACKAGES} |
| USERVER_DOWNLOAD_PACKAGE_FMT | Download and setup Fmt if no Fmt of matching version was found | ${USERVER_DOWNLOAD_PACKAGES} |
| USERVER_DOWNLOAD_PACKAGE_GBENCH | Download and setup gbench if no gbench of matching version was found | ${USERVER_DOWNLOAD_PACKAGES} |
| USERVER_DOWNLOAD_PACKAGE_GRPC | Download and setup gRPC if no gRPC of matching version was found | ${USERVER_DOWNLOAD_PACKAGES} |
| USERVER_DOWNLOAD_PACKAGE_GTEST | Download and setup gtest if no gtest of matching version was found | ${USERVER_DOWNLOAD_PACKAGES} |
| USERVER_DOWNLOAD_PACKAGE_PROTOBUF | Download and setup Protobuf if no Protobuf of matching version was found | ${USERVER_DOWNLOAD_PACKAGE_GRPC} |
| USERVER_DOWNLOAD_PACKAGE_KAFKA | Download and setup librdkafka if no librdkafka matching version was found | ${USERVER_DOWNLOAD_PACKAGES} |
| USERVER_DOWNLOAD_PACKAGE_YDBCPPSDK | Download and setup ydb-cpp-sdk if no ydb-cpp-sdk of matching version was found | ${USERVER_DOWNLOAD_PACKAGES} |
| USERVER_FORCE_DOWNLOAD_PACKAGES | Download all possible third-party packages even if there is an installed system package | OFF |
| USERVER_INSTALL | Build userver for further installation | OFF |
| USERVER_IS_THE_ROOT_PROJECT | Contributor mode: build userver tests, samples and helper tools | auto-detects if userver is the top level project |
| USERVER_GOOGLE_COMMON_PROTOS_TARGET | Name of cmake target preparing google common proto library | Builds userver-api-common-protos |
| USERVER_GOOGLE_COMMON_PROTOS | Path to the folder with google common proto files | Downloads automatically |
| USERVER_PG_SERVER_INCLUDE_DIR | Path to the folder with PostgreSQL server headers, for example /usr/include/postgresql/15/server | autodetected |
| USERVER_PG_SERVER_LIBRARY_DIR | Path to the folder with PostgreSQL server libraries, for example /usr/lib/postgresql/15/lib | autodetected |
| USERVER_PG_INCLUDE_DIR | Path to the folder with PostgreSQL libpq headers, for example /usr/local/include | autodetected |
| USERVER_PG_LIBRARY_DIR | Path to the folder with PostgreSQL libpq libraries, for example /usr/local/lib | autodetected |
| USERVER_MYSQL_ALLOW_BUGGY_LIBMARIADB | Allows mysql driver to leak memory instead of aborting in some rare cases when linked against libmariadb3<3.3.4 | OFF |
| USERVER_DISABLE_PHDR_CACHE | Disable caching of dl_phdr_info items, which interferes with dlopen | OFF |
| USERVER_DISABLE_RSEQ_ACCELERATION | Disable rseq-based optimizations, which may not work depending on kernel/glibc/distro/etc version | OFF for x86 Linux, ON otherwise |
| USERVER_FEATURE_UBOOST_CORO | Build with vendored version of Boost.context and Boost.coroutine2, is needed for sanitizers builds | ON |
To explicitly specialize the compiler use the cmake options CMAKE_C_COMPILER and CMAKE_CXX_COMPILER. For example to use clang-12 compiler install it and add the following options to cmake: -DCMAKE_CXX_COMPILER=clang++-12 -DCMAKE_C_COMPILER=clang-12
USERVER_LTO.userver is split into multiple CMake libraries.
| CMake target | CMake option to enable building the library | Component for install | Main documentation page |
|---|---|---|---|
userver-universal | Always on | universal | The C++ Asynchronous Framework |
userver-core | USERVER_FEATURE_CORE (ON by default) | core | The C++ Asynchronous Framework |
userver-grpc | USERVER_FEATURE_GRPC | grpc | gRPC |
userver-mongo | USERVER_FEATURE_MONGODB | mongo | MongoDB |
userver-postgresql | USERVER_FEATURE_POSTGRESQL | postgresql | uPg Driver |
userver-redis | USERVER_FEATURE_REDIS | redis | Redis |
userver-clickhouse | USERVER_FEATURE_CLICKHOUSE | clickhouse | ClickHouse Driver |
userver-kafka | USERVER_FEATURE_KAFKA | kafka | Apache Kafka - EXPERIMENTAL |
userver-rabbitmq | USERVER_FEATURE_RABBITMQ | rabbitmq | RabbitMQ (AMQP 0-9-1) - EXPERIMENTAL |
userver-mysql | USERVER_FEATURE_MYSQL | mysql | MySQL driver design and implementation details |
userver-rocks | USERVER_FEATURE_ROCKS | rocks | TODO |
userver-ydb | USERVER_FEATURE_YDB | ydb | TODO |
For installed userver or Conan, cmake targets are named like userver::{component}, for instance: userver::core, userver::mysql, etc
Make sure to:
The details vary depending on the method of building userver:
add_subsirectory(userver) as used in service templatesuserver uses CPM for downloading missing packages.
By default, we first try to find the corresponding system package. With USERVER_FORCE_DOWNLOAD_PACKAGES=ON, no such attempt is made, and we skip straight to CPMAddPackage. This can be useful to guarantee that the build uses the latest (known to userver) versions of third-party packages.
You can control the usage of CPM with USERVER_DOWNLOAD_* options. For example, USERVER_DOWNLOAD_PACKAGES=OFF is useful for CI and other controlled environments to make sure that no download attempts are made, which ensures repeatability and the best CI build speed.
For details on the download options, refer to CPM documentation. Some advice:
CPM_SOURCE_CACHE helps to avoid re-downloads with multiple userver build modes or multiple CPM-using projects;CPM_USE_NAMED_CACHE_DIRECTORIES (which userver enables by default) avoids junk library names shown in IDEs.userver itself can be downloaded and built using CPM.
Make sure to enable the CMake options to build userver libraries you need, then link to those libraries.
There are prepared and ready to use service templates at the github:
Just use the template to make your own service:
git clone your-service-repo && cd your-service-repo && git submodule update --initFor local development of your service either
make docker-test;Makefile.local file to provide platform-specific CMake options to the template:The service templates allow to kickstart the development of your production-ready service, but there can't be a repo for each and every combination of userver libraries. To use additional userver libraries, e.g. userver-grpc, add to the root CMakeLists.txt:
See tutorial_services for minimal usage examples of various userver libraries.
Dependencies: third_party/userver/scripts/docs/en/deps/ubuntu-22.04.md
Dependencies could be installed via:
The Docker image ghcr.io/userver-framework/ubuntu-22.04-userver-pg:latest provides a container with all the build dependencies, PostgreSQL and userver preinstalled and with a proper setup of PPAs with databases, compilers, tools.
To run it just use a command like
The Docker image ghcr.io/userver-framework/ubuntu-22.04-userver:latest provides a container with all the build dependencies and userver preinstalled and with a proper setup of PPAs with databases, compilers, tools.
To run it just use a command like
The Docker image ghcr.io/userver-framework/ubuntu-22.04-userver-base:latest provides a container with all the build dependencies preinstalled and with a proper setup of PPAs with databases, compilers and tools.
To run it just use a command like
After that, install the databases and compiler you are planning to use via apt install and start developing.
scripts/docker/ubuntu-22.04-pg.dockerfile, scripts/docker/ubuntu-22.04.dockerfile and scripts/docker/base-ubuntu-22.04.dockerfile respectively. See scripts/docker/ directory and Building Docker container for userver for more inspiration on building your own custom docker containers.The userver framework is available at Yandex Cloud Marketplace.
To create a VM with preinstalled userver just click the "Create VM" button and pay for the Cloud hardware usage.
After that the VM is ready to use. SSH to it and use find_package(userver REQUIRED) in the CMakeLists.txt to use the preinstalled userver framework.
If there a need to update the userver in the VM do the following:
Dependencies: third_party/userver/scripts/docs/en/deps/ubuntu-21.10.md
Dependencies could be installed via:
Dependencies: third_party/userver/scripts/docs/en/deps/ubuntu-20.04.md
Dependencies could be installed via:
Recommended Makefile.local:
Dependencies: third_party/userver/scripts/docs/en/deps/ubuntu-18.04.md
Dependencies could be installed via:
Recommended Makefile.local:
Dependencies: third_party/userver/scripts/docs/en/deps/debian-11.md
Dependencies: third_party/userver/scripts/docs/en/deps/debian-11.md (same as above)
Recommended Makefile.local:
Dependencies: third_party/userver/scripts/docs/en/deps/fedora-35.md
Fedora dependencies could be installed via:
Recommended Makefile.local:
Dependencies: third_party/userver/scripts/docs/en/deps/fedora-36.md
Fedora dependencies could be installed via:
Recommended Makefile.local:
Dependencies: third_party/userver/scripts/docs/en/deps/gentoo.md
Dependencies could be installed via:
Recommended Makefile.local:
Dependencies: third_party/userver/scripts/docs/en/deps/arch.md
Using an AUR helper (pikaur in this example) the dependencies could be installed as:
Without AUR:
Recommended Makefile.local:
Dependencies: third_party/userver/scripts/docs/en/deps/macos.md. At least MacOS 10.15 required with Xcode and Homebrew.
Dependencies could be installed via:
Recommended Makefile.local:
After that the make test would build and run the service tests.
🐙 userver works well on modern POSIX platforms. Follow the cmake hints for the installation of required packets and experiment with the CMake options.
Feel free to provide a PR with instructions for your favorite platform at https://github.com/userver-framework/userver.
If there's a strong need to build only the userver and run its tests, then see Build instructions for userver
You can install userver globally and then use it from anywhere with find_package. Make sure to use the same build mode as for your service, otherwise subtle linkage issues will arise. To install userver build it with USERVER_INSTALL=ON flags in Debug and Release modes:
Next, write
in your CMakeLists.txt. Choose only the necessary components.
Finally, link your source with userver component.
For instance:
Done! You can use installed userver.
Link mariadbclient additionally for mysql component:
If CMake option USERVER_FEATURE_PATCH_LIBPQ is on, then the same developer version of libpq, libpgport and libpgcommon libraries should be available on the system. If there are multiple versions of those libraries use USERVER_PG_* CMake options to aid the build system in finding the right version.
You could also install any version of the above libraries by explicitly pinning the version. For example in Debian/Ubuntu pinning to version 14 could be done via the following commands: