gRPC C++ — сборка из исходников

В этом документе содержатся подробные инструкции по сборке gRPC C++ из исходников. Обратите внимание, что данное руководство охватывает только сборку gRPC и предназначено в основном для вкладчиков gRPC C++ и/или продвинутых пользователей. Другие пользователи должны следовать инструкциям для пользователей. См. Как использовать для руководства по добавлению gRPC в качестве зависимости в C++ приложение (есть несколько способов, и установка на уровне системы часто не является наилучшим выбором).

Предварительные требования

Linux

 $ [sudo] apt-get install build-essential autoconf libtool pkg-config

Если вы планируете сборку с использованием CMake

 $ [sudo] apt-get install cmake

Если вы являетесь вкладчиком и планируете сборку и запуск тестов, установите следующее:

 $ # clang и библиотека LLVM C++ требуется только для сборок с санитайзерами
 $ [sudo] apt-get install clang libc++-dev

MacOS

На Mac вам сначала нужно установить Xcode или Командные инструменты для Xcode и затем выполнить следующую команду из терминала:

 $ [sudo] xcode-select --install

Чтобы собрать gRPC из исходников, вам может потребоваться установить следующие пакеты из Homebrew:

 $ brew install autoconf automake libtool shtool

Если вы планируете сборку с использованием CMake, следуйте инструкциям с сайта https://cmake.org/download/*Подсказка*: при сборке вы можете захотеть явно установить переменные окружения LIBTOOL и LIBTOOLIZE при выполнении команды make, чтобы убедиться, что используется версия, установленная с помощью brew:

$ LIBTOOL=glibtool LIBTOOLIZE=glibtoolize make

Windows

Чтобы подготовиться к сборке с использованием CMake и компилятора Microsoft Visual C++

• Установите Visual Studio 2017 или более позднюю версию (будет использоваться компилятор Visual C++).
• Установите Git.
• Установите CMake.
• Установите NASM и добавьте его в PATH (choco install nasm) - требуется для boringssl
• (Необязательно) Установите Ninja (choco install ninja)

Клонирование репозитория (включая подмодули)

Перед сборкой вам нужно клонировать репозиторий gRPC GitHub и загрузить подмодули, содержащие исходный код для зависимостей gRPC (это делается с помощью команды submodule или флага --recursive). Используйте следующие команды для клонирования репозитория gRPC по последней стабильной версии тега.

Unix

$ git clone -b RELEASE_TAG_HERE https://github.com/grpc/grpc
$ cd grpc
$ git submodule update --init

Windows

> git clone -b RELEASE_TAG_HERE https://github.com/grpc/grpc
> cd grpc
> git submodule update --init

ЗАМЕЧАНИЕ: Построитель bazel использует другую модель для зависимостей. Вам нужно будет скачать подмодули только в том случае, если вы используете что-то другое, кроме bazel (например, cmake).# Построение из исходного кода

В мире C++ нет "стандартной" системы сборки, которая бы работала во всех поддерживаемых случаях и на всех поддерживаемых платформах. Поэтому, gRPC поддерживает несколько основных систем сборки, которые должны удовлетворить большинство пользователей. В зависимости от ваших потребностей мы рекомендуем использовать bazel или cmake для сборки.

Сборка с использованием bazel (рекомендуется)

Bazel является основной системой сборки для gRPC C++ и если вы уверены в использовании bazel, мы можем однозначно его рекомендовать. Использование bazel обеспечит вам лучший опыт разработчика, а также более быстрые и чистые сборки.

Вам потребуется версия bazel 1.0.0 или выше для сборки gRPC. См. Установка Bazel для инструкций по установке bazel на вашей системе. Мы поддерживаем сборку с использованием bazel на Linux, MacOS и Windows.

Из корневого каталога репозитория grpc

# Сборка gRPC C++
$ bazel build :all

# Запуск всех тестов C/C++
$ bazel test --config=dbg //test/...

ЗАМЕЧАНИЕ: Если вы являетесь поддерживаемым разработчиком gRPC и у вас есть доступ к нашему тестовому кластеру, вы должны использовать окружение удалённой сборки gRPC для значительного ускорения сборки и тестирования (а также для множества других очень полезных функций).## Сборка с использованием CMake

Linux/Unix, Использование Make

Запустите из каталога grpc после клонирования репозитория с параметром --recursive или обновления подмодулей.

$ mkdir -p cmake/build
$ cd cmake/build
$ cmake ../..
$ make

Если вы хотите собрать общедоступные библиотеки (файлы .so), запустите cmake с параметром -DBUILD_SHARED_LIBS=ON.

Windows, Использование Visual Studio 2015 или 2017

При использовании генератора "Visual Studio", cmake сгенерирует решение (grpc.sln), которое будет содержать проект для Visual Studio для каждой цели, определенной в CMakeLists.txt (+ несколько дополнительных удобных проектов, добавленных автоматически cmake). После открытия решения с помощью Visual Studio вы сможете просматривать и компилировать код.

> @rem Запустите из директории grpc после клонирования репозитория с параметром --recursive или обновления подмодулей.
> md .build
> cd .build
> cmake .. -G "Visual Studio 14 2015"
> cmake --build . --config Release

Использование gRPC C++ в виде DLL не рекомендуется, но его можно включить, запустив cmake с параметром -DBUILD_SHARED_LIBS=ON.

Windows, используя Ninja (быстрее сборка).

Обратите внимание, что при использовании Ninja вам все равно потребуется Visual C++ (часть Visual Studio) для компиляции C/C++ исходных кодов.

> @rem Запустите из директории grpc после клонирования репозитория с параметром --recursive или обновления подмодулей.
> cd cmake
> md build
> cd build
> call "%VS140COMNTOOLS%..\..\VC\vcvarsall.bat" x64
> cmake ..\.. -GNinja -DCMAKE_BUILD_TYPE=Release
> cmake --build .
```Использование gRPC C++ в виде DLL не рекомендуется, но его можно включить, запустив `cmake` с параметром `-DBUILD_SHARED_LIBS=ON`.

### Windows: Примечание по сборке shared libs (DLLs)

Сборка DLL на Windows поддерживается на основе "лучших усилий", и мы не рекомендуем использовать gRPC C++ в виде DLL, так как есть известные недостатки, связанные с работой C++ DLL на Windows. Например, нет стабильного C++ ABI, и вы не можете безопасно выделять память в одной DLL и освобождать её в другой.

Тем не менее, мы не активно запрещаем сборку DLL на Windows (она может быть включена в cmake с параметром `-DBUILD_SHARED_LIBS=ON`), и вы можете использовать сборки DLL на свой страх и риск.
- вы были предупреждены, что есть некоторые важные недостатки, и некоторые вещи могут вообще не работать или будут сломаны интересным образом.
- у нас нет обширного тестирования для сборок DLL (чтобы избежать затрат на поддержку, увеличения времени тестирования и т.д.), поэтому могут возникнуть регрессии / сбои сборки.

### Управление зависимостями

Система сборки CMake для gRPC имеет два варианта для управления зависимостями.
CMake может собрать зависимости для вас, или он может найти библиотеки,
которые уже установлены на вашей системе и использовать их для сборки gRPC.

Это поведение контролируется переменными CMake `gRPC_<depname>_PROVIDER`,
например, `gRPC_CARES_PROVIDER`. Варианты, которые эти переменные принимают, следующие:* модуль — сборка зависимостей вместе с gRPC. Исходный код получается из git подмодулей gRPC.
* пакет — использование внешних копий зависимостей, которые уже доступны на вашей системе. Эти зависимости могут быть установлены вашим системным менеджером пакетов или, возможно, вы предварительно установили их с помощью CMake с параметром `CMAKE_INSTALL_PREFIX`. Например, если вы установите `gRPC_CARES_PROVIDER=module`, тогда CMake будет собирать c-ares перед сборкой gRPC. С другой стороны, если вы установите `gRPC_CARES_PROVIDER=package`, тогда CMake будет искать уже установленную на вашей системе копию c-ares и использовать её для сборки gRPC.

### Установка после сборки

Выполните следующие шаги для установки gRPC с помощью CMake.
* Установите `-DgRPC_INSTALL=ON`
* Соберите целевую цель `install`

Цель установки контролируется переменной
[`CMAKE_INSTALL_PREFIX`](https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html).

Если вы используете CMake версии 3.13 или выше, вы можете собрать зависимости gRPC в режиме "модуль" и установить их вместе с gRPC за один шаг.
[Пример](test/distrib/cpp/run_distrib_test_cmake_module_install.sh)

Если вы собираете gRPC < 1.27 или используете CMake < 3.13, вам потребуется выбрать режим "пакет" (вместо режима "модуль") для зависимостей.
Это означает, что вам потребуются внешние копии этих библиотек на вашей системе. Этот [пример](test/distrib/cpp/run_distrib_test_cmake.sh) показывает, как установить зависимости с помощью cmake перед установкой gRPC.```
# ЗАМЕЧАНИЕ: все зависимости gRPC должны быть уже установлены
$ cmake ../.. -DgRPC_INSTALL=ON                \
              -DCMAKE_BUILD_TYPE=Release       \
              -DgRPC_ABSL_PROVIDER=package     \
              -DgRPC_CARES_PROVIDER=package    \
              -DgRPC_PROTOBUF_PROVIDER=package \
              -DgRPC_RE2_PROVIDER=package      \
              -DgRPC_SSL_PROVIDER=package      \
              -DgRPC_ZLIB_PROVIDER=package
$ make
$ make install

Кросс-компиляция

Вы можете использовать CMake для кросс-компиляции gRPC для другой архитектуры. Для этого вам сначала нужно собрать protoc и grpc_cpp_plugin для архитектуры хоста. Эти инструменты используются во время сборки gRPC, поэтому нам нужны копии исполняемых файлов, которые могут быть запущены нативно.

Вероятно, вам потребуется установить инструментарий для платформы, на которую вы собираетесь кросс-компилировать. После этого вы можете написать файл инструментария, чтобы сообщить CMake, где найти компиляторы и системные инструменты, которые будут использоваться для этой сборки.

Этот файл инструментария указывается CMake с помощью переменной CMAKE_TOOLCHAIN_FILE.

$ cmake ../.. -DCMAKE_TOOLCHAIN_FILE=path/to/file
$ make

Пример кросс-компиляции

Примечание о SONAME и его влиянии на совместимость ABI в сборке CMake

При нарушении ABI (API совместимости) предпринимаются все усилия для увеличения ревизии SONAME. Хотя изменение SONAME явно указывает на несовместимость ABI, нельзя дать твердых гарантий относительно какой-либо стабильности ABI для той же версии SONAME.

ЗАМЕЧАНИЕ: `make` ранее был основной системой сборки для gRPC, но мы больше не рекомендуем её. Вы должны использовать `bazel` или `cmake`. Файл `Makefile` предназначен только для внутреннего использования и не предназначен для публичного использования.

Из корневой директории репозитория grpc
```sh
 $ make

ЗАМЕЧАНИЕ: если вы получаете ошибку на Linux, например, 'aclocal-1.15: command not found', что может произойти, если вы запустили make до установки предварительных требований, попробуйте следующее:

$ git clean -f -d -x && git submodule foreach --recursive git clean -f -d -x
$ [sudo] apt-get install build-essential autoconf libtool pkg-config
$ make

Примечание о protoc

По умолчанию gRPC использует protocol buffers, вам потребуется компилятор protoc для генерации шаблонного кода сервера и клиента.

Если вы собираете gRPC из исходного кода, как описано выше, файл Makefile автоматически попытается скомпилировать protoc из папки third_party, если вы клонировали репозиторий рекурсивно и он обнаруживает, что у вас ещё нет установленного компилятора protoc.