diff --git a/.gitignore b/.gitignore index 0d3c9a79677d..f4a103d21214 100644 --- a/.gitignore +++ b/.gitignore @@ -4,7 +4,7 @@ .mypy_cache .pytest_cache *.orig -*.local +/Makefile.local *.yawiki .ccache/ .cache/ diff --git a/.mapping.json b/.mapping.json index 79090b3f6731..2e8ff39a2213 100644 --- a/.mapping.json +++ b/.mapping.json @@ -3569,6 +3569,7 @@ "scripts/docs/en/userver/tutorial/tcp_service.md":"taxi/uservices/userver/scripts/docs/en/userver/tutorial/tcp_service.md", "scripts/docs/en/userver/tutorial/websocket_service.md":"taxi/uservices/userver/scripts/docs/en/userver/tutorial/websocket_service.md", "scripts/docs/en/userver/ydb.md":"taxi/uservices/userver/scripts/docs/en/userver/ydb.md", + "scripts/docs/examples/service-template/CMakeUserPresets.json.example":"taxi/uservices/userver/scripts/docs/examples/service-template/CMakeUserPresets.json.example", "scripts/docs/fontello/README.txt":"taxi/uservices/userver/scripts/docs/fontello/README.txt", "scripts/docs/fontello/config.json":"taxi/uservices/userver/scripts/docs/fontello/config.json", "scripts/docs/fontello/css/animation.css":"taxi/uservices/userver/scripts/docs/fontello/css/animation.css", diff --git a/scripts/docs/doxygen.conf b/scripts/docs/doxygen.conf index 960440268abf..dc0d224af434 100644 --- a/scripts/docs/doxygen.conf +++ b/scripts/docs/doxygen.conf @@ -1128,7 +1128,11 @@ EXCLUDE_SYMBOLS = impl \ # that contain example code fragments that are included (see the \include # command). -EXAMPLE_PATH = universal/src \ +EXAMPLE_PATH = samples \ + cmake \ + testsuite \ + scripts/docs/examples \ + universal/src \ universal/utest/src \ chaotic/integration_tests \ core/src \ @@ -1158,10 +1162,7 @@ EXAMPLE_PATH = universal/src \ ydb/functional_tests \ otlp/src \ otlp/tests \ - samples \ - cmake \ - libraries/easy/samples \ - testsuite + libraries/easy/samples # If the value of the EXAMPLE_PATH tag contains directories, you can use the # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and diff --git a/scripts/docs/en/userver/build/build.md b/scripts/docs/en/userver/build/build.md index 63f817dac499..57260a8621e4 100644 --- a/scripts/docs/en/userver/build/build.md +++ b/scripts/docs/en/userver/build/build.md @@ -3,41 +3,25 @@ @anchor quick_start_for_beginners ## Quick start for beginners -If you are new to userver it is a good idea to start with using the `service template` git repository to design your first userver-based service. +1\. Press the "Use this template" button at the top right of the +[GitHub template page](https://github.com/userver-framework/service_template). -@warning @ref https://github.com/userver-framework/service_template.git "service_template" has no database. If you need a database please use other @ref service_templates "service templates". - -For a service without a database use https://github.com/userver-framework/service_template - -1\. Clone `service template` and userver repositories. +@warning @ref https://github.com/userver-framework/service_template "service_template" has no databases and uses HTTP. +If you need gRPC or a database, please use other @ref service_templates "templates". +2\. Clone the service: ```shell -git clone --depth 1 https://github.com/userver-framework/service_template.git && \ -git clone --depth 1 https://github.com/userver-framework/userver.git service_template/third_party/userver && \ -cd service_template +git clone https://github.com/your-username/your-service.git && cd your-service ``` -More information about `hello service` can be found here: @ref scripts/docs/en/userver/tutorial/hello_service.md - -2\. Install userver dependencies. - -There is an option to use a @ref docker_with_ubuntu_22_04 "docker container". +3\. @ref ways_to_get_userver "Get userver". -Alternatively you can install @ref scripts/docs/en/userver/build/dependencies.md "build dependencies" for userver. - -For example to install @ref ubuntu_22_04 build dependencies: - -```shell -sudo apt update && \ -sudo apt install --allow-downgrades -y $(cat third_party/userver/scripts/docs/en/deps/ubuntu-22.04.md | tr '\n' ' ') -``` - -3\. Build and start your service. +4\. Build and start your service. Run in the service repo root: ```shell make build-release && \ -make service-start-release +make start-release ``` During the build, you can make a coffee break until approximately the following output appears: @@ -56,7 +40,7 @@ DEBUG Incoming connection from ::ffff:127.0.0.1, fd 43 ``` -4\. Try to send a request. +5\. Try to send a request. ```shell curl http://127.0.0.1:8080/hello?name=userver @@ -69,50 +53,143 @@ The answer should be something like this: Hello, userver! ``` -5\. Now you are ready for fast and comfortable creation of C++ microservices, services and utilities! +Now you are ready for fast and comfortable creation of C++ microservices, services and utilities! @anchor service_templates ## Service templates for userver based services -There are prepared and ready to use service templates at the github: +There are ready to use service templates at GitHub: -| Link | Contains | -| ---------------------------------------------------------------- | ---------------- | -| https://github.com/userver-framework/service_template | | -| https://github.com/userver-framework/pg_service_template | postgreSQL | -| https://github.com/userver-framework/pg_grpc_service_template | postgreSQL, gRPC | +| Link | Contains | +|------------------------------------------------------------------|------------------------| +| https://github.com/userver-framework/service_template | HTTP | +| https://github.com/userver-framework/pg_service_template | HTTP, PostgreSQL | +| https://github.com/userver-framework/pg_grpc_service_template | HTTP, PostgreSQL, gRPC | +| https://github.com/userver-framework/mongo_grpc_service_template | HTTP, MongoDB, gRPC | -Just use the template to make your own service: +To create a service: -1. Press the green "Use this template" button at the top of the github template page +1. Press the "Use this template" button at the top right of the GitHub template page 2. Clone the service `git clone your-service-repo && cd your-service-repo` 3. Give a proper name to your service and replace all the occurrences of "*service_template" string with that name. 4. Feel free to tweak, adjust or fully rewrite the source code of your service. -For local development of your service either +You'll need to @ref ways_to_get_userver "get userver" before proceeding with local development. + +More information on the project directory structure can be found +@ref scripts/docs/en/userver/tutorial/hello_service.md "here". -* use the docker build and tests run via `make docker-test`; -* or install the build dependencies on your local system and - adjust the `Makefile.local` file to provide \b platform-specific \b CMake - options to the template: +@anchor service_templates_libraries +### Using additional userver libraries in service templates 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`: ```cmake -set(USERVER_FEATURE_GRPC ON CACHE BOOL "" FORCE) -# ... -add_subdirectory(third_party/userver) -# ... -target_link_libraries(${PROJECT_NAME} userver::grpc) +find_package(userver COMPONENTS core grpc QUIET) ``` +Then add the corresponding option to @ref service_templates_presets "cmake presets", +e.g. `"USERVER_FEATURE_GRPC": "ON"`. + @see @ref userver_libraries -@see @ref cmake_options See @ref tutorial_services for minimal usage examples of various userver libraries. +@anchor service_templates_presets +### Managing cmake options in service templates + +@note If you use @userver_install "installed userver", then for most options to take effect, you need to uninstall +userver (if already installed), then install again, passing the desired cmake options. + +Service templates use [cmake presets](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html) for managing +service's cmake options. If you DON'T use installed userver and build userver together with the service, +then userver also takes its @ref cmake_options "cmake options" from there. + +If an option has semantic meaning (should be committed to VCS and applied in CI), +then it should be added to `CMakePresets.json`: + +```json +{ + "configurePresets": [ + { + "name": "common-flags", + "cacheVariables": { + "USERVER_FEATURE_GRPC": "ON", + "USERVER_SOME_OPTION": "WHAT" + } + } + ] +} +``` + +If an option only configures local build (should NOT be commited to VCS and applied in CI), +then it should instead be added to `CMakeUserPresets.json`: + +* @ref service-template/CMakeUserPresets.json.example + +Service's `Makefile` supports custom presets through additional targets like +`cmake-debug-custom`, `cmake-release-custom`, `build-debug-custom`, etc. + +@anchor ways_to_get_userver +## Ways to get userver + +You can download prebuilt userver using one of the following ways: + +1) @ref devcontainers "Docker (Dev Containers)" ← recommended for beginners; +2) @ref docker_with_ubuntu_22_04 "Docker (manual)"; +3) @ref prebuilt_deb_package "prebuilt Debian package"; +4) @ref userver_conan "Conan"; + +Alternatively, install @ref scripts/docs/en/userver/build/dependencies.md "build dependencies" for userver, +then build userver in one of the following ways: + +5) @ref userver_install "install userver"; +6) let the service template download and build userver as a subdirectory using (@ref userver_cpm "CPM"); +7) pass a path to custom userver location to `download_userver()`, then let the service + @ref service_templates_presets "build userver as a subdirectory". + +@anchor devcontainers +## Dev Containers + +Dev Containers is the easiest and least problematic way to get prebuilt userver together with its dependencies. + +1. Install Docker + + * Linux: + ```shell + curl https://get.docker.com/ | sudo sh + ``` + Allow + [usage without sudo](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user) + (reboot is required) and + [configure service start on boot](https://docs.docker.com/engine/install/linux-postinstall/#configure-docker-to-start-on-boot-with-systemd). + + * [macOS](https://docs.docker.com/desktop/setup/install/mac-install/) + +2. Install IDE extension + + * [VSCode](https://code.visualstudio.com/docs/devcontainers/containers): `ms-vscode-remote.remote-containers` + * [CLion](https://www.jetbrains.com/help/clion/connect-to-devcontainer.html): "Dev Containers" (**note:** beta) + +3. Open the service project. If CMake asks to configure, deny + +4. Agree to reopen the project in a Dev Container + +5. The Docker container for development will automatically be downloaded (~6GB, may take a while), unpacked and run + using the config from + [.devcontainer](https://github.com/userver-framework/service_template/tree/develop/.devcontainer) + directory + +6. When prompted, select `Debug` cmake preset + +7. (Optional) + [Share Git credentials](https://code.visualstudio.com/remote/advancedcontainers/sharing-git-credentials) + with the container to perform VCS operations from the IDE + +8. You can configure, build, debug and run tests using either the IDE itself or `Makefile` (see the service's README.md) + using the IDE's integrated terminal ## Downloading packages using CPM @@ -136,26 +213,19 @@ Some advice: ### Downloading userver using CPM userver itself can be downloaded and built using CPM. +In fact, this is what +[download_userver()](https://github.com/userver-framework/service_template/blob/develop/cmake/DownloadUserver.cmake) +function does in @ref service_templates "service templates" by default. -```cmake -CPMAddPackage( - NAME userver - VERSION (userver release version or git commit hash) - GIT_TAG (userver release version or git commit hash) - GITHUB_REPOSITORY userver-framework/userver - OPTIONS - "USERVER_FEATURE_GRPC ON" -) - -target_link_libraries(${PROJECT_NAME} userver::grpc) -``` +`download_userver()` just calls `CPMAddPackage` with some defaults, so you can pin userver `VERSION` or `GIT_TAG` +for reproducible builds. -First, install build dependencies. There are options: +When acquiring userver via CPM, you first need to install build dependencies. There are options: * install @ref scripts/docs/en/userver/build/dependencies.md "build dependencies" * or use base image of @ref docker_with_ubuntu_22_04 -Make sure to enable the CMake options to build userver libraries you need, +Make sure to @ref service_templates_presets "enable" the CMake options to build userver libraries you need, then link to those libraries. @see @ref cmake_options @@ -195,10 +265,11 @@ sudo dpkg -i ./libuserver-all-dev*.deb ### Install with cmake --install @warning installing userver with cmake --install is NOT recommended due to update and uninstall issues. -Please @ref userver_install_debian_package "build and install Debian package" instead. +Please, @ref userver_install_debian_package "build and install Debian package" instead. To install userver build it with `USERVER_INSTALL=ON` flags in `Debug` and `Release` modes: -```cmake + +```shell cmake -S./ -B./build_debug \ -DCMAKE_BUILD_TYPE=Debug \ -DUSERVER_INSTALL=ON \ @@ -284,6 +355,15 @@ Alternatively see @ref userver_install "userver install" inspiration on building your own custom docker containers. +@anchor prebuilt_deb_package +### Using a prebuilt Debian package for Ubuntu 22.04 + +You can download and install a `.deb` package that is attached to each +[userver release](https://github.com/userver-framework/userver/releases). + +The package currently targets Ubuntu 22.04, for other Ubuntu versions your mileage may vary. + + @anchor userver_conan ## Conan @@ -363,3 +443,6 @@ The resulting binary should be 2-15% faster than without PGO, depending on the c @htmlonly
@endhtmlonly ⇦ @ref scripts/docs/en/userver/faq.md | @ref scripts/docs/en/userver/build/dependencies.md ⇨ @htmlonly
@endhtmlonly + +@example service-template/CMakeUserPresets.json.example +@example service-template/Makefile.local diff --git a/scripts/docs/en/userver/build/dependencies.md b/scripts/docs/en/userver/build/dependencies.md index 2ab0760f83a6..39ea3eb07f3f 100644 --- a/scripts/docs/en/userver/build/dependencies.md +++ b/scripts/docs/en/userver/build/dependencies.md @@ -1,10 +1,7 @@ # Build dependencies -@note In case you struggle with setting up userver dependencies there are other options: - -* Prebuilt `.deb` package in each release of userver framework -* @ref docker_with_ubuntu_22_04 "Docker" -* @ref userver_conan "Conan" +@note In case you struggle with setting up userver dependencies, +there are @ref ways_to_get_userver "options to use prebuilt userver". ## Platform-specific build dependencies @@ -16,10 +13,11 @@ Paths to dependencies start from the @ref service_templates "directory of your s \b Dependencies: @ref scripts/docs/en/deps/ubuntu-24.04.md "third_party/userver/scripts/docs/en/deps/ubuntu-24.04.md" -Dependencies could be installed via: +Dependencies can be installed via: ```bash -sudo apt install --allow-downgrades -y $(cat third_party/userver/scripts/docs/en/deps/ubuntu-24.04.md | tr '\n' ' ') +DEPS_FILE="https://raw.githubusercontent.com/userver-framework/userver/refs/heads/develop/scripts/docs/en/deps/ubuntu-24.04.md" && \ +sudo apt install --allow-downgrades -y $(wget -q -O - ${DEPS_FILE}) ``` @anchor ubuntu_22_04 @@ -27,20 +25,22 @@ sudo apt install --allow-downgrades -y $(cat third_party/userver/scripts/docs/en \b Dependencies: @ref scripts/docs/en/deps/ubuntu-22.04.md "third_party/userver/scripts/docs/en/deps/ubuntu-22.04.md" -Dependencies could be installed via: +Dependencies can be installed via: ```bash -sudo apt install --allow-downgrades -y $(cat third_party/userver/scripts/docs/en/deps/ubuntu-22.04.md | tr '\n' ' ') +DEPS_FILE="https://raw.githubusercontent.com/userver-framework/userver/refs/heads/develop/scripts/docs/en/deps/ubuntu-22.04.md" && \ +sudo apt install --allow-downgrades -y $(wget -q -O - ${DEPS_FILE}) ``` ### Ubuntu 21.10 (Impish Indri) \b Dependencies: @ref scripts/docs/en/deps/ubuntu-21.10.md "third_party/userver/scripts/docs/en/deps/ubuntu-21.10.md" -Dependencies could be installed via: +Dependencies can be installed via: ```bash -sudo apt install --allow-downgrades -y $(cat third_party/userver/scripts/docs/en/deps/ubuntu-21.10.md | tr '\n' ' ') +DEPS_FILE="https://raw.githubusercontent.com/userver-framework/userver/refs/heads/develop/scripts/docs/en/deps/ubuntu-21.10.md" && \ +sudo apt install --allow-downgrades -y $(wget -q -O - ${DEPS_FILE}) ``` @@ -48,18 +48,18 @@ sudo apt install --allow-downgrades -y $(cat third_party/userver/scripts/docs/en \b Dependencies: @ref scripts/docs/en/deps/ubuntu-20.04.md "third_party/userver/scripts/docs/en/deps/ubuntu-20.04.md" -Dependencies could be installed via: +Dependencies can be installed via: ```bash -sudo apt install --allow-downgrades -y $(cat third_party/userver/scripts/docs/en/deps/ubuntu-20.04.md | tr '\n' ' ') +DEPS_FILE="https://raw.githubusercontent.com/userver-framework/userver/refs/heads/develop/scripts/docs/en/deps/ubuntu-20.04.md" && \ +sudo apt install --allow-downgrades -y $(wget -q -O - ${DEPS_FILE}) ``` -\b Recommended \b Makefile.local: +Recommended CMake options: -```cmake -CMAKE_COMMON_FLAGS += \ - -DUSERVER_FEATURE_CRYPTOPP_BLAKE2=0 \ - -DUSERVER_FEATURE_REDIS_HI_MALLOC=1 +``` +USERVER_FEATURE_CRYPTOPP_BLAKE2=0 +USERVER_FEATURE_REDIS_HI_MALLOC=1 ``` @@ -67,21 +67,21 @@ CMAKE_COMMON_FLAGS += \ \b Dependencies: @ref scripts/docs/en/deps/ubuntu-18.04.md "third_party/userver/scripts/docs/en/deps/ubuntu-18.04.md" -Dependencies could be installed via: - ``` - bash - sudo apt install --allow-downgrades -y $(cat third_party/userver/scripts/docs/en/deps/ubuntu-18.04.md | tr '\n' ' ') - ``` +Dependencies can be installed via: -\b Recommended \b Makefile.local: +```bash +DEPS_FILE="https://raw.githubusercontent.com/userver-framework/userver/refs/heads/develop/scripts/docs/en/deps/ubuntu-18.04.md" && \ +sudo apt install --allow-downgrades -y $(wget -q -O - ${DEPS_FILE}) +``` + +Recommended CMake options: -```cmake -CMAKE_COMMON_FLAGS += \ - -DCMAKE_CXX_COMPILER=g++-8 \ - -DCMAKE_C_COMPILER=gcc-8 \ - -DUSERVER_FEATURE_CRYPTOPP_BLAKE2=0 \ - -DUSERVER_FEATURE_CRYPTOPP_BASE64_URL=0 \ - -DUSERVER_USE_LD=gold +``` +CMAKE_CXX_COMPILER=g++-8 +CMAKE_C_COMPILER=gcc-8 +USERVER_FEATURE_CRYPTOPP_BLAKE2=0 +USERVER_FEATURE_CRYPTOPP_BASE64_URL=0 +USERVER_USE_LD=gold ``` @@ -89,14 +89,21 @@ CMAKE_COMMON_FLAGS += \ \b Dependencies: @ref scripts/docs/en/deps/debian-11.md "third_party/userver/scripts/docs/en/deps/debian-11.md" +Dependencies can be installed via: + +```bash +DEPS_FILE="https://raw.githubusercontent.com/userver-framework/userver/refs/heads/develop/scripts/docs/en/deps/debian-11.md" && \ +sudo apt install --allow-downgrades -y $(wget -q -O - ${DEPS_FILE}) +``` + ### Debian 11 32-bit -\b Dependencies: @ref scripts/docs/en/deps/debian-11.md "third_party/userver/scripts/docs/en/deps/debian-11.md" (same as above) +\b Dependencies are the same as above. -\b Recommended \b Makefile.local: +Recommended CMake options: -```cmake +```Makefile CMAKE_COMMON_FLAGS += \ -DCMAKE_C_FLAGS='-D_FILE_OFFSET_BITS=64' \ -DCMAKE_CXX_FLAGS='-D_FILE_OFFSET_BITS=64' @@ -106,53 +113,53 @@ CMAKE_COMMON_FLAGS += \ \b Dependencies: @ref scripts/docs/en/deps/fedora-36.md "third_party/userver/scripts/docs/en/deps/fedora-35.md" -Fedora dependencies could be installed via: +Dependencies can be installed via: ```bash -sudo dnf install -y $(cat third_party/userver/scripts/docs/en/deps/fedora-35.md | tr '\n' ' ') +DEPS_FILE="https://raw.githubusercontent.com/userver-framework/userver/refs/heads/develop/scripts/docs/en/deps/fedora-35.md" && \ +sudo dnf install -y $(wget -q -O - ${DEPS_FILE}) ``` -\b Recommended \b Makefile.local: +Recommended CMake options: -```cmake -CMAKE_COMMON_FLAGS += \ - -DUSERVER_FEATURE_STACKTRACE=0 \ - -DUSERVER_FEATURE_PATCH_LIBPQ=0 +``` +USERVER_FEATURE_STACKTRACE=0 +USERVER_FEATURE_PATCH_LIBPQ=0 ``` ### Fedora 36 \b Dependencies: @ref scripts/docs/en/deps/fedora-36.md "third_party/userver/scripts/docs/en/deps/fedora-36.md" -Fedora dependencies could be installed via: +Dependencies can be installed via: ```bash -sudo dnf install -y $(cat third_party/userver/scripts/docs/en/deps/fedora-36.md | tr '\n' ' ') +DEPS_FILE="https://raw.githubusercontent.com/userver-framework/userver/refs/heads/develop/scripts/docs/en/deps/fedora-36.md" && \ +sudo dnf install -y $(wget -q -O - ${DEPS_FILE}) ``` -\b Recommended \b Makefile.local: +Recommended CMake options: -```cmake -CMAKE_COMMON_FLAGS += \ - -DUSERVER_FEATURE_STACKTRACE=0 \ - -DUSERVER_FEATURE_PATCH_LIBPQ=0 +``` +USERVER_FEATURE_STACKTRACE=0 +USERVER_FEATURE_PATCH_LIBPQ=0 ``` ### Gentoo \b Dependencies: @ref scripts/docs/en/deps/gentoo.md "third_party/userver/scripts/docs/en/deps/gentoo.md" -Dependencies could be installed via: +Dependencies can be installed via: ```bash -sudo emerge --ask --update --oneshot $(cat scripts/docs/en/deps/gentoo.md | tr '\n' ' ') +DEPS_FILE="https://raw.githubusercontent.com/userver-framework/userver/refs/heads/develop/scripts/docs/en/deps/gentoo.md" && \ +sudo emerge --ask --update --oneshot $(wget -q -O - ${DEPS_FILE}) ``` -\b Recommended \b Makefile.local: +Recommended CMake options: -```cmake -CMAKE_COMMON_FLAGS += \ - -DUSERVER_CHECK_PACKAGE_VERSIONS=0 +``` +USERVER_CHECK_PACKAGE_VERSIONS=0 ``` @@ -160,21 +167,21 @@ CMAKE_COMMON_FLAGS += \ \b Dependencies: @ref scripts/docs/en/deps/alpine.md "third_party/userver/scripts/docs/en/deps/alpine.md" -Dependencies could be installed via: +Dependencies can be installed via: ```bash -sudo apk add $(cat scripts/docs/en/deps/alpine.md) +DEPS_FILE="https://raw.githubusercontent.com/userver-framework/userver/refs/heads/develop/scripts/docs/en/deps/alpine.md" && \ +sudo apk add $(wget -q -O - ${DEPS_FILE}) ``` -\b Recommended \b Makefile.local: +Recommended CMake options: -```cmake -CMAKE_COMMON_FLAGS += \ - -DUSERVER_FEATURE_JEMALLOC=OFF \ - -DUSERVER_FEATURE_STACKTRACE=OFF \ - -DUSERVER_FEATURE_KAFKA=OFF \ - -DUSERVER_DOWNLOAD_PACKAGE_PROTOBUF=ON \ - -DUSERVER_DISABLE_RSEQ_ACCELERATION=YES +``` +USERVER_FEATURE_JEMALLOC=OFF +USERVER_FEATURE_STACKTRACE=OFF +USERVER_FEATURE_KAFKA=OFF +USERVER_DOWNLOAD_PACKAGE_PROTOBUF=ON +USERVER_DISABLE_RSEQ_ACCELERATION=YES ``` @@ -182,17 +189,19 @@ CMAKE_COMMON_FLAGS += \ \b Dependencies: @ref scripts/docs/en/deps/arch.md "third_party/userver/scripts/docs/en/deps/arch.md" -Using an AUR helper (pikaur in this example) the dependencies could be installed as: +Using an AUR helper (pikaur in this example) the dependencies can be installed as: ```bash -pikaur -S $(cat third_party/userver/scripts/docs/en/deps/arch.md | sed 's/^makepkg|//g' | tr '\n' ' ') +DEPS_FILE="https://raw.githubusercontent.com/userver-framework/userver/refs/heads/develop/scripts/docs/en/deps/arch.md" && \ +pikaur -S $(wget -q -O - ${DEPS_FILE} | sed 's/^makepkg|//g') ``` Without AUR: ```bash -sudo pacman -S $(cat third_party/userver/scripts/docs/en/deps/arch.md | grep -v -- 'makepkg|' | tr '\n' ' ') -cat third_party/userver/scripts/docs/en/deps/arch.md | grep -oP '^makepkg\|\K.*' | while read ;\ +DEPS_FILE="https://raw.githubusercontent.com/userver-framework/userver/refs/heads/develop/scripts/docs/en/deps/arch.md" && \ +sudo pacman -S $(wget -q -O - ${DEPS_FILE} | grep -v -- 'makepkg|') +wget -q -O - ${DEPS_FILE} | grep -oP '^makepkg\|\K.*' | while read ;\ do \ DIR=$(mktemp -d) ;\ git clone https://aur.archlinux.org/$REPLY.git $DIR ;\ @@ -203,33 +212,34 @@ cat third_party/userver/scripts/docs/en/deps/arch.md | grep -oP '^makepkg\|\K.*' done ``` -\b Recommended \b Makefile.local: - -```cmake -CMAKE_COMMON_FLAGS += \ - -DUSERVER_FEATURE_PATCH_LIBPQ=0 +Recommended CMake options: + +``` +USERVER_FEATURE_PATCH_LIBPQ=0 ``` -### MacOS +### macOS \b Dependencies: @ref scripts/docs/en/deps/macos.md "third_party/userver/scripts/docs/en/deps/macos.md". -At least MacOS 10.15 required with +At least macOS 10.15 required with [Xcode](https://apps.apple.com/us/app/xcode/id497799835) and [Homebrew](https://brew.sh/). -Dependencies could be installed via: +Dependencies can be installed via: ```bash -brew install $(cat third_party/userver/scripts/docs/en/deps/macos.md | tr '\n' ' ') +DEPS_FILE="https://raw.githubusercontent.com/userver-framework/userver/refs/heads/develop/scripts/docs/en/deps/arch.md" && \ +brew install $(wget -q -O - ${DEPS_FILE}) ``` Some Homebrew packages are keg-only (they are not symlinked to Homebrew prefix path e.g. `/opt/homebrew`), therefore they can not be found by CMake in configure phase. -It it possible to symlink the libraries using `brew link --force`. +It is possible to symlink the libraries using `brew link --force`. + +For current macOS build dependencies, userver expects that following packages are symlinked: -For current MacOS build dependencies, userver expects that following packages are symlinked: ```bash brew link postgresql@16 # postgresql is keg-only (required by PostgreSQL) brew link --force openldap # keg-only (required by PostgreSQL) @@ -239,16 +249,16 @@ brew link --force curl # keg-only (required by Core) brew link --force cyrus-sasl # keg-only (required by Mongo and Kafka) ``` -\b Recommended \b Makefile.local: - -```cmake -CMAKE_COMMON_FLAGS += \ - -DUSERVER_CHECK_PACKAGE_VERSIONS=0 \ - -DUSERVER_FEATURE_REDIS_HI_MALLOC=1 \ - -DUSERVER_FEATURE_CRYPTOPP_BLAKE2=0 - -DUSERVER_FORCE_DOWNLOAD_ABSEIL=1 \ - -DUSERVER_FORCE_DOWNLOAD_PROTOBUF=1 \ - -DUSERVER_FORCE_DOWNLOAD_GRPC=1 +Recommended CMake options: + +```Makefile +USERVER_CHECK_PACKAGE_VERSIONS=0 +USERVER_FEATURE_REDIS_HI_MALLOC=1 +USERVER_FEATURE_CRYPTOPP_BLAKE2=0 +USERVER_FORCE_DOWNLOAD_ABSEIL=1 +USERVER_FORCE_DOWNLOAD_RE2=1 +USERVER_FORCE_DOWNLOAD_PROTOBUF=1 +USERVER_FORCE_DOWNLOAD_GRPC=1 ``` After that the `make test` would build and run the service tests. diff --git a/scripts/docs/en/userver/build/options.md b/scripts/docs/en/userver/build/options.md index 1f4d19e4e720..c4f2401c39bc 100644 --- a/scripts/docs/en/userver/build/options.md +++ b/scripts/docs/en/userver/build/options.md @@ -39,7 +39,7 @@ Make sure to: The details vary depending on the method of building userver: -* `add_subdirectory(userver)` as used in @ref service_templates "service templates" +* `find_package` + CPM + CMake Presets as used in @ref service_templates "service templates" * @ref userver_install "userver install" * @ref userver_cpm "CPM" * @ref userver_conan "Conan" @@ -55,6 +55,11 @@ For example, to use `clang-12` compiler, install it and add the following option cmake ... -DCMAKE_C_COMPILER=clang-12 -DCMAKE_CXX_COMPILER=clang++-12 ``` +The exact format of setting cmake options varies depending on the method of building userver: + +* `find_package` + CPM + CMake Presets as used in @ref service_templates "service templates" +* @ref userver_install "userver install" + ### CMake options for selecting userver libraries to build | Option | Description | Default | diff --git a/scripts/docs/en/userver/grpc.md b/scripts/docs/en/userver/grpc.md index 06c20cc7b7cd..eda49bd22af1 100644 --- a/scripts/docs/en/userver/grpc.md +++ b/scripts/docs/en/userver/grpc.md @@ -363,3 +363,10 @@ These are the metrics provided for each gRPC method: @htmlonly
@endhtmlonly ⇦ @ref scripts/docs/en/userver/profile_context_switches.md | @ref scripts/docs/en/userver/grpc_server_middlewares.md ⇨ @htmlonly
@endhtmlonly + +@example grpc-generic-proxy/src/proxy_service.hpp +@example grpc-generic-proxy/src/proxy_service.cpp +@example grpc-generic-proxy/main.cpp +@example grpc-generic-proxy/static_config.yaml +@example grpc-generic-proxy/config_vars.yaml +@example grpc-generic-proxy/CMakeLists.txt diff --git a/scripts/docs/examples/service-template/CMakeUserPresets.json.example b/scripts/docs/examples/service-template/CMakeUserPresets.json.example new file mode 100644 index 000000000000..5c5acddd12d2 --- /dev/null +++ b/scripts/docs/examples/service-template/CMakeUserPresets.json.example @@ -0,0 +1,47 @@ +{ + "version": 2, + "cmakeMinimumRequired": { + "major": 3, + "minor": 20, + "patch": 0 + }, + "configurePresets": [ + { + "name": "debug-custom", + "displayName": "Debug Custom", + "description": "Debug build with custom options", + "inherits": [ + "custom-flags" + ], + "binaryDir": "${sourceDir}/build_debug", + "cacheVariables": { + "CMAKE_BUILD_TYPE": "Debug", + "USERVER_SANITIZE": "addr;ub" + } + }, + { + "name": "debug-custom", + "displayName": "Release Custom", + "description": "Release build with custom options", + "inherits": [ + "custom-flags" + ], + "binaryDir": "${sourceDir}/build_release", + "cacheVariables": { + "CMAKE_BUILD_TYPE": "Release" + } + }, + { + "name": "custom-flags", + "hidden": true, + "generator": "Ninja", + "inherits": [ + "common-flags" + ], + "cacheVariables": { + "CMAKE_C_COMPILER": "clang", + "CMAKE_CXX_COMPILER": "clang++" + } + } + ] +}