Note: if your target project is not a Google project then first read the main README about the purpose of BoringSSL.
If you are porting BoringSSL to a new platform see “go/boringssl-on-new-platform” (Google Internal) for information about porting BoringSSL to a new platform for a Google project.
BoringSSL usage typically follows a “live at head” model. Projects pin to whatever the current latest of BoringSSL is at the time of update, and regularly update it to pick up new changes.
Some systems cannot consume git revisions and expect git tags. BoringSSL tags periodic snapshots as “releases”, to meet the needs of those systems. These versions do not represent any kind of stability or development milestone. BoringSSL does not branch at these releases and will not cherry-pick bugfixes to them. Unless there is a technical constraint to use one of these revisions, projects should simply use the latest untagged revision when updating.
While the BoringSSL repository may contain project-specific branches, e.g. chromium-2214, those are not supported release branches and must not as such. In rare cases, BoringSSL will temporarily maintain a short-lived branch on behalf of a project. Most such branches are no longer updated, because the corresponding project no longer needs them, and we do not create new ones to replace the ones that are no longer updated. E.g., not every Chromium release branch has a corresponding BoringSSL chromium-* branch. Even while active, the branch may not contain all changes relevant to a general BoringSSL consumer.
If you are using Bazel then you can use the boringssl module in the Bazel Central Registry with bzlmod. Look up the latest version and add the following to your MODULE.bazel file:
bazel_dep(name = "boringssl", version = "INSERT_VERSION_HERE")
Substitute the latest version in for INSERT_VERSION_HERE.
BoringSSL will periodically ship snapshots to Bazel Central Registry. As with other dependencies, periodically keep the referenced version up-to-date.
Typically projects create a third_party/boringssl directory to put BoringSSL-specific files into. The source code of BoringSSL itself goes into third_party/boringssl/src, either by copying or as a submodule.
It‘s generally a mistake to put BoringSSL’s source code into third_party/boringssl directly because custom build files need to go somewhere and merging these with the BoringSSL source code makes updating things more complex.
BoringSSL is designed to work with many different build systems. The project currently has CMake and Bazel builds checked in. Other build systems, and embedders with custom build needs, are supported by separating the source list, maintained by BoringSSL, and the top-level build logic, maintained by the embedder.
Source lists for various build systems are pre-generated and live in the gen directory. For example, source lists for GN live in gen/sources.gni. There is also a generic gen/sources.json file for projects to consume if needed. util/build/build.go describes what the various source lists mean. Most projects should concatenate the bcm and crypto targets.
If you don't use any of the supported build systems, you should augment the util/pregenerate tool to support it, or consume gen/sources.json.
Historically, source lists were generated at update time with the util/generate_build_files.py script. We are in the process of transitioning builds to the pre-generated files, so that embedders do not need to run a custom script when updating BoringSSL.
BoringSSL does not present a lot of configurability in order to reduce the number of configurations that need to be tested. But there are a couple of #defines that you may wish to set:
OPENSSL_NO_ASM prevents the use of assembly code (although it‘s up to you to ensure that the build system doesn’t link it in if you wish to reduce binary size). This will have a significant performance impact but can be useful if you wish to use tools like AddressSanitizer that interact poorly with assembly code.
OPENSSL_SMALL removes some code that is especially large at some performance cost.
You cannot link multiple versions of BoringSSL or OpenSSL into a single binary without dealing with symbol conflicts. If you are statically linking multiple versions together, there‘s not a lot that can be done because C doesn’t have a module system.
If you are using multiple versions in a single binary, in different shared objects, ensure you build BoringSSL with -fvisibility=hidden and do not export any of BoringSSL's symbols. This will prevent any collisions with other verisons that may be included in other shared objects. Note that this requires that all callers of BoringSSL APIs live in the same shared object as BoringSSL.
If you require that BoringSSL APIs be used across shared object boundaries, continue to build with -fvisibility=hidden but define BORINGSSL_SHARED_LIBRARY in both BoringSSL and consumers. BoringSSL‘s own source files (but not consumers’ source files) must also build with BORINGSSL_IMPLEMENTATION defined. This will export BoringSSL's public symbols in the resulting shared object while hiding private symbols. However note that, as with a static link, this precludes dynamically linking with another version of BoringSSL or OpenSSL.