Skip to content

Commit adab557

Browse files
Anton3Anton3
committed
feat docs: add docs on cmake presets and devcontainers
commit_hash:b96033b4db07edcc453b883df6fb5976f199718a
1 parent ff61803 commit adab557

File tree

8 files changed

+312
-158
lines changed

8 files changed

+312
-158
lines changed

‎.gitignore

+1-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
.mypy_cache
55
.pytest_cache
66
*.orig
7-
*.local
7+
/Makefile.local
88
*.yawiki
99
.ccache/
1010
.cache/

‎.mapping.json

+1
Original file line numberDiff line numberDiff line change
@@ -3569,6 +3569,7 @@
35693569
"scripts/docs/en/userver/tutorial/tcp_service.md":"taxi/uservices/userver/scripts/docs/en/userver/tutorial/tcp_service.md",
35703570
"scripts/docs/en/userver/tutorial/websocket_service.md":"taxi/uservices/userver/scripts/docs/en/userver/tutorial/websocket_service.md",
35713571
"scripts/docs/en/userver/ydb.md":"taxi/uservices/userver/scripts/docs/en/userver/ydb.md",
3572+
"scripts/docs/examples/service-template/CMakeUserPresets.json.example":"taxi/uservices/userver/scripts/docs/examples/service-template/CMakeUserPresets.json.example",
35723573
"scripts/docs/fontello/README.txt":"taxi/uservices/userver/scripts/docs/fontello/README.txt",
35733574
"scripts/docs/fontello/config.json":"taxi/uservices/userver/scripts/docs/fontello/config.json",
35743575
"scripts/docs/fontello/css/animation.css":"taxi/uservices/userver/scripts/docs/fontello/css/animation.css",

‎scripts/docs/doxygen.conf

+6-5
Original file line numberDiff line numberDiff line change
@@ -1128,7 +1128,11 @@ EXCLUDE_SYMBOLS = impl \
11281128
# that contain example code fragments that are included (see the \include
11291129
# command).
11301130

1131-
EXAMPLE_PATH = universal/src \
1131+
EXAMPLE_PATH = samples \
1132+
cmake \
1133+
testsuite \
1134+
scripts/docs/examples \
1135+
universal/src \
11321136
universal/utest/src \
11331137
chaotic/integration_tests \
11341138
core/src \
@@ -1158,10 +1162,7 @@ EXAMPLE_PATH = universal/src \
11581162
ydb/functional_tests \
11591163
otlp/src \
11601164
otlp/tests \
1161-
samples \
1162-
cmake \
1163-
libraries/easy/samples \
1164-
testsuite
1165+
libraries/easy/samples
11651166

11661167
# If the value of the EXAMPLE_PATH tag contains directories, you can use the
11671168
# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and

‎scripts/docs/en/userver/build/build.md

+145-62
Original file line numberDiff line numberDiff line change
@@ -3,41 +3,25 @@
33
@anchor quick_start_for_beginners
44
## Quick start for beginners
55

6-
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.
6+
1\. Press the "Use this template" button at the top right of the
7+
[GitHub template page](https://github.com/userver-framework/service_template).
78

8-
@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".
9-
10-
For a service without a database use https://github.com/userver-framework/service_template
11-
12-
1\. Clone `service template` and userver repositories.
9+
@warning @ref https://github.com/userver-framework/service_template "service_template" has no databases and uses HTTP.
10+
If you need gRPC or a database, please use other @ref service_templates "templates".
1311

12+
2\. Clone the service:
1413

1514
```shell
16-
git clone --depth 1 https://github.com/userver-framework/service_template.git && \
17-
git clone --depth 1 https://github.com/userver-framework/userver.git service_template/third_party/userver && \
18-
cd service_template
15+
git clone https://github.com/your-username/your-service.git && cd your-service
1916
```
2017

21-
More information about `hello service` can be found here: @ref scripts/docs/en/userver/tutorial/hello_service.md
22-
23-
2\. Install userver dependencies.
24-
25-
There is an option to use a @ref docker_with_ubuntu_22_04 "docker container".
18+
3\. @ref ways_to_get_userver "Get userver".
2619

27-
Alternatively you can install @ref scripts/docs/en/userver/build/dependencies.md "build dependencies" for userver.
28-
29-
For example to install @ref ubuntu_22_04 build dependencies:
30-
31-
```shell
32-
sudo apt update && \
33-
sudo apt install --allow-downgrades -y $(cat third_party/userver/scripts/docs/en/deps/ubuntu-22.04.md | tr '\n' ' ')
34-
```
35-
36-
3\. Build and start your service.
20+
4\. Build and start your service. Run in the service repo root:
3721

3822
```shell
3923
make build-release && \
40-
make service-start-release
24+
make start-release
4125
```
4226

4327
During the build, you can make a coffee break until approximately the following output appears:
@@ -56,7 +40,7 @@ DEBUG <userver> Incoming connection from ::ffff:127.0.0.1, fd 43
5640

5741
```
5842

59-
4\. Try to send a request.
43+
5\. Try to send a request.
6044

6145
```shell
6246
curl http://127.0.0.1:8080/hello?name=userver
@@ -69,50 +53,143 @@ The answer should be something like this:
6953
Hello, userver!
7054
```
7155

72-
5\. Now you are ready for fast and comfortable creation of C++ microservices, services and utilities!
56+
Now you are ready for fast and comfortable creation of C++ microservices, services and utilities!
7357

7458
@anchor service_templates
7559
## Service templates for userver based services
7660

77-
There are prepared and ready to use service templates at the github:
61+
There are ready to use service templates at GitHub:
7862

79-
| Link | Contains |
80-
| ---------------------------------------------------------------- | ---------------- |
81-
| https://github.com/userver-framework/service_template | |
82-
| https://github.com/userver-framework/pg_service_template | postgreSQL |
83-
| https://github.com/userver-framework/pg_grpc_service_template | postgreSQL, gRPC |
63+
| Link | Contains |
64+
|------------------------------------------------------------------|------------------------|
65+
| https://github.com/userver-framework/service_template | HTTP |
66+
| https://github.com/userver-framework/pg_service_template | HTTP, PostgreSQL |
67+
| https://github.com/userver-framework/pg_grpc_service_template | HTTP, PostgreSQL, gRPC |
68+
| https://github.com/userver-framework/mongo_grpc_service_template | HTTP, MongoDB, gRPC |
8469

85-
Just use the template to make your own service:
70+
To create a service:
8671

87-
1. Press the green "Use this template" button at the top of the github template page
72+
1. Press the "Use this template" button at the top right of the GitHub template page
8873
2. Clone the service `git clone your-service-repo && cd your-service-repo`
8974
3. Give a proper name to your service and replace all the occurrences of "*service_template" string with that name.
9075
4. Feel free to tweak, adjust or fully rewrite the source code of your service.
9176

92-
For local development of your service either
77+
You'll need to @ref ways_to_get_userver "get userver" before proceeding with local development.
78+
79+
More information on the project directory structure can be found
80+
@ref scripts/docs/en/userver/tutorial/hello_service.md "here".
9381

94-
* use the docker build and tests run via `make docker-test`;
95-
* or install the build dependencies on your local system and
96-
adjust the `Makefile.local` file to provide \b platform-specific \b CMake
97-
options to the template:
82+
@anchor service_templates_libraries
83+
### Using additional userver libraries in service templates
9884

9985
The service templates allow to kickstart the development of your production-ready service,
10086
but there can't be a repo for each and every combination of userver libraries.
10187
To use additional userver libraries, e.g. `userver::grpc`, add to the root `CMakeLists.txt`:
10288

10389
```cmake
104-
set(USERVER_FEATURE_GRPC ON CACHE BOOL "" FORCE)
105-
# ...
106-
add_subdirectory(third_party/userver)
107-
# ...
108-
target_link_libraries(${PROJECT_NAME} userver::grpc)
90+
find_package(userver COMPONENTS core grpc QUIET)
10991
```
11092

93+
Then add the corresponding option to @ref service_templates_presets "cmake presets",
94+
e.g. `"USERVER_FEATURE_GRPC": "ON"`.
95+
11196
@see @ref userver_libraries
112-
@see @ref cmake_options
11397

11498
See @ref tutorial_services for minimal usage examples of various userver libraries.
11599

100+
@anchor service_templates_presets
101+
### Managing cmake options in service templates
102+
103+
@note If you use @userver_install "installed userver", then for most options to take effect, you need to uninstall
104+
userver (if already installed), then install again, passing the desired cmake options.
105+
106+
Service templates use [cmake presets](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html) for managing
107+
service's cmake options. If you DON'T use installed userver and build userver together with the service,
108+
then userver also takes its @ref cmake_options "cmake options" from there.
109+
110+
If an option has semantic meaning (should be committed to VCS and applied in CI),
111+
then it should be added to `CMakePresets.json`:
112+
113+
```json
114+
{
115+
"configurePresets": [
116+
{
117+
"name": "common-flags",
118+
"cacheVariables": {
119+
"USERVER_FEATURE_GRPC": "ON",
120+
"USERVER_SOME_OPTION": "WHAT"
121+
}
122+
}
123+
]
124+
}
125+
```
126+
127+
If an option only configures local build (should NOT be commited to VCS and applied in CI),
128+
then it should instead be added to `CMakeUserPresets.json`:
129+
130+
* @ref service-template/CMakeUserPresets.json.example
131+
132+
Service's `Makefile` supports custom presets through additional targets like
133+
`cmake-debug-custom`, `cmake-release-custom`, `build-debug-custom`, etc.
134+
135+
@anchor ways_to_get_userver
136+
## Ways to get userver
137+
138+
You can download prebuilt userver using one of the following ways:
139+
140+
1) @ref devcontainers "Docker (Dev Containers)" ← recommended for beginners;
141+
2) @ref docker_with_ubuntu_22_04 "Docker (manual)";
142+
3) @ref prebuilt_deb_package "prebuilt Debian package";
143+
4) @ref userver_conan "Conan";
144+
145+
Alternatively, install @ref scripts/docs/en/userver/build/dependencies.md "build dependencies" for userver,
146+
then build userver in one of the following ways:
147+
148+
5) @ref userver_install "install userver";
149+
6) let the service template download and build userver as a subdirectory using (@ref userver_cpm "CPM");
150+
7) pass a path to custom userver location to `download_userver()`, then let the service
151+
@ref service_templates_presets "build userver as a subdirectory".
152+
153+
@anchor devcontainers
154+
## Dev Containers
155+
156+
Dev Containers is the easiest and least problematic way to get prebuilt userver together with its dependencies.
157+
158+
1. Install Docker
159+
160+
* Linux:
161+
```shell
162+
curl https://get.docker.com/ | sudo sh
163+
```
164+
Allow
165+
[usage without sudo](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user)
166+
(reboot is required) and
167+
[configure service start on boot](https://docs.docker.com/engine/install/linux-postinstall/#configure-docker-to-start-on-boot-with-systemd).
168+
169+
* [macOS](https://docs.docker.com/desktop/setup/install/mac-install/)
170+
171+
2. Install IDE extension
172+
173+
* [VSCode](https://code.visualstudio.com/docs/devcontainers/containers): `ms-vscode-remote.remote-containers`
174+
* [CLion](https://www.jetbrains.com/help/clion/connect-to-devcontainer.html): "Dev Containers" (**note:** beta)
175+
176+
3. Open the service project. If CMake asks to configure, deny
177+
178+
4. Agree to reopen the project in a Dev Container
179+
180+
5. The Docker container for development will automatically be downloaded (~6GB, may take a while), unpacked and run
181+
using the config from
182+
[.devcontainer](https://github.com/userver-framework/service_template/tree/develop/.devcontainer)
183+
directory
184+
185+
6. When prompted, select `Debug` cmake preset
186+
187+
7. (Optional)
188+
[Share Git credentials](https://code.visualstudio.com/remote/advancedcontainers/sharing-git-credentials)
189+
with the container to perform VCS operations from the IDE
190+
191+
8. You can configure, build, debug and run tests using either the IDE itself or `Makefile` (see the service's README.md)
192+
using the IDE's integrated terminal
116193

117194
## Downloading packages using CPM
118195

@@ -136,26 +213,19 @@ Some advice:
136213
### Downloading userver using CPM
137214

138215
userver itself can be downloaded and built using CPM.
216+
In fact, this is what
217+
[download_userver()](https://github.com/userver-framework/service_template/blob/develop/cmake/DownloadUserver.cmake)
218+
function does in @ref service_templates "service templates" by default.
139219

140-
```cmake
141-
CPMAddPackage(
142-
NAME userver
143-
VERSION (userver release version or git commit hash)
144-
GIT_TAG (userver release version or git commit hash)
145-
GITHUB_REPOSITORY userver-framework/userver
146-
OPTIONS
147-
"USERVER_FEATURE_GRPC ON"
148-
)
149-
150-
target_link_libraries(${PROJECT_NAME} userver::grpc)
151-
```
220+
`download_userver()` just calls `CPMAddPackage` with some defaults, so you can pin userver `VERSION` or `GIT_TAG`
221+
for reproducible builds.
152222
153-
First, install build dependencies. There are options:
223+
When acquiring userver via CPM, you first need to install build dependencies. There are options:
154224
155225
* install @ref scripts/docs/en/userver/build/dependencies.md "build dependencies"
156226
* or use base image of @ref docker_with_ubuntu_22_04
157227
158-
Make sure to enable the CMake options to build userver libraries you need,
228+
Make sure to @ref service_templates_presets "enable" the CMake options to build userver libraries you need,
159229
then link to those libraries.
160230
161231
@see @ref cmake_options
@@ -195,10 +265,11 @@ sudo dpkg -i ./libuserver-all-dev*.deb
195265
### Install with cmake --install
196266
197267
@warning installing userver with cmake --install is NOT recommended due to update and uninstall issues.
198-
Please @ref userver_install_debian_package "build and install Debian package" instead.
268+
Please, @ref userver_install_debian_package "build and install Debian package" instead.
199269
200270
To install userver build it with `USERVER_INSTALL=ON` flags in `Debug` and `Release` modes:
201-
```cmake
271+
272+
```shell
202273
cmake -S./ -B./build_debug \
203274
-DCMAKE_BUILD_TYPE=Debug \
204275
-DUSERVER_INSTALL=ON \
@@ -284,6 +355,15 @@ Alternatively see @ref userver_install "userver install"
284355
inspiration on building your own custom docker containers.
285356
286357
358+
@anchor prebuilt_deb_package
359+
### Using a prebuilt Debian package for Ubuntu 22.04
360+
361+
You can download and install a `.deb` package that is attached to each
362+
[userver release](https://github.com/userver-framework/userver/releases).
363+
364+
The package currently targets Ubuntu 22.04, for other Ubuntu versions your mileage may vary.
365+
366+
287367
@anchor userver_conan
288368
## Conan
289369
@@ -363,3 +443,6 @@ The resulting binary should be 2-15% faster than without PGO, depending on the c
363443
@htmlonly <div class="bottom-nav"> @endhtmlonly
364444
⇦ @ref scripts/docs/en/userver/faq.md | @ref scripts/docs/en/userver/build/dependencies.md ⇨
365445
@htmlonly </div> @endhtmlonly
446+
447+
@example service-template/CMakeUserPresets.json.example
448+
@example service-template/Makefile.local

0 commit comments

Comments
 (0)