Включение BoringSSL в проект

Примечание: если ваш целевой проект не является проектом Google, сначала ознакомьтесь с основным файлом README о назначении BoringSSL.

Bazel

Если вы используете Bazel (https://bazel.build), то можете включить BoringSSL как внешний репозиторий, используя коммит из ветки master-with-bazel. Эта ветка поддерживается ботом из master и включает необходимые сгенерированные файлы и файл верхнего уровня BUILD.

Например:

git_repository(
    name = "boringssl",
    commit = "_some commit_",
    remote = "https://boringssl.googlesource.com/boringssl"
)

Вам всё равно нужно будет поддерживать актуальность указанного коммита, если на него есть ссылка.

Структура каталогов

Обычно проекты создают каталог third_party/boringssl для размещения файлов, специфичных для BoringSSL. Исходный код самого BoringSSL помещается в third_party/boringssl/src путём копирования или в качестве подмодуля.

Как правило, ошибочно помещать исходный код BoringSSL непосредственно в third_party/boringssl, потому что предварительно созданные файлы и пользовательские файлы сборки должны куда-то идти, а объединение их с исходным кодом BoringSSL усложняет обновление.

Поддержка сборки

BoringSSL предназначен для работы со многими различными системами сборки. В настоящее время различные проекты используют GYP (https://gyp.gsrc.io/), GN (https://gn.googlesource.com/gn/+/master/docs/quick_start.md), Bazel (https://bazel.build/) и Make (https://www.gnu.org/software/make/) для сборки BoringSSL без особых проблем.

Система разработки — CMake, и она знает, как автоматически генерировать промежуточные файлы, которые нужны BoringSSL. Однако за пределами среды CMake эти промежуточные файлы генерируются один раз и проверяются в исходном репозитории проекта. Это позволяет избежать необходимости поддержки Perl и Go в своих системах сборки.

Скрипт util/generate_build_files.py должен запускаться из каталога third_party/boringssl и находить исходный код BoringSSL в src/. Вы должны передать ему один аргумент: имя используемой вами системы сборки. Если вы не используете ни одну из поддерживаемых систем сборки, вам следует дополнить generate_build_files.py поддержкой для неё.

Скрипт предварительно сгенерирует промежуточные файлы (подробности о том, какие инструменты необходимо установить, см. в BUILDING.md) и выведет вспомогательные файлы для этой системы сборки. Он не генерирует полный скрипт сборки, только списки файлов и тестов, которые часто меняются. Например, посмотрите на файл и тест, сгенерированный для GN в Chromium.

Обычно эти сгенерированные файлы вместе с рукописными файлами сборки проверяют. Периодически инженер обновляет версию BoringSSL, регенерирует эти файлы и проверяет обновлённый результат. Как пример, посмотрите, как это делается в Chromium.

Определения

BoringSSL не предоставляет много возможностей для настройки, чтобы уменьшить количество конфигураций, которые необходимо протестировать. Но есть пара #defines, которые вы, возможно, захотите установить:

• OPENSSL_NO_ASM предотвращает использование кода сборки (хотя вы сами должны убедиться, что система сборки не связывает его, если хотите уменьшить размер двоичного файла). Это значительно повлияет на производительность, но может быть полезно, если вы хотите использовать такие инструменты, как AddressSanitizer (http://clang.llvm.org/docs/AddressSanitizer.html), которые плохо взаимодействуют с кодом сборки.
• OPENSSL_SMALL удаляет некоторый особенно большой код за счёт некоторой потери производительности.

Символы

Вы не можете связать несколько версий BoringSSL или OpenSSL в одном двоичном файле без решения конфликтов символов. Если вы статически связываете несколько Если вы используете несколько версий в одном двоичном файле, в разных общих объектах, убедитесь, что вы собираете BoringSSL с параметром -fvisibility=hidden и не экспортируете ни один из символов BoringSSL. Это предотвратит любые конфликты с другими версиями, которые могут быть включены в другие общие объекты. Обратите внимание, что это требует, чтобы все вызывающие API BoringSSL находились в том же общем объекте, что и BoringSSL.

Если вам требуется, чтобы API BoringSSL использовались через границы общих объектов, продолжайте сборку с -fvisibility=hidden, но определите BORINGSSL_SHARED_LIBRARY как в BoringSSL, так и у потребителей. Собственные исходные файлы BoringSSL (но не исходные файлы потребителей) также должны собираться с определённым BORINGSSL_IMPLEMENTATION. Это позволит экспортировать публичные символы BoringSSL в результирующий общий объект, скрывая при этом частные символы. Однако обратите внимание, что, как и в случае статической компоновки, это исключает динамическое связывание с другой версией BoringSSL или OpenSSL.