1# Incorporating BoringSSL into a project 2 3**Note**: if your target project is not a Google project then first read the 4[main README](/README.md) about the purpose of BoringSSL. 5 6## Bazel 7 8If you are using [Bazel](https://bazel.build) then you can incorporate 9BoringSSL as an external repository by using a commit from the 10`master-with-bazel` branch. That branch is maintained by a bot from `master` 11and includes the needed generated files and a top-level BUILD file. 12 13For example: 14 15 git_repository( 16 name = "boringssl", 17 commit = "_some commit_", 18 remote = "https://boringssl.googlesource.com/boringssl", 19 ) 20 21You would still need to keep the referenced commit up to date if a specific 22commit is referred to. 23 24## Directory layout 25 26Typically projects create a `third_party/boringssl` directory to put 27BoringSSL-specific files into. The source code of BoringSSL itself goes into 28`third_party/boringssl/src`, either by copying or as a 29[submodule](https://git-scm.com/docs/git-submodule). 30 31It's generally a mistake to put BoringSSL's source code into 32`third_party/boringssl` directly because pre-built files and custom build files 33need to go somewhere and merging these with the BoringSSL source code makes 34updating things more complex. 35 36## Build support 37 38BoringSSL is designed to work with many different build systems. Currently, 39different projects use [GYP](https://gyp.gsrc.io/), 40[GN](https://chromium.googlesource.com/chromium/src/+/master/tools/gn/docs/quick_start.md), 41[Bazel](https://bazel.build/) and [Make](https://www.gnu.org/software/make/) to 42build BoringSSL, without too much pain. 43 44The development build system is CMake and the CMake build knows how to 45automatically generate the intermediate files that BoringSSL needs. However, 46outside of the CMake environment, these intermediates are generated once and 47checked into the incorporating project's source repository. This avoids 48incorporating projects needing to support Perl and Go in their build systems. 49 50The script [`util/generate_build_files.py`](/util/generate_build_files.py) 51expects to be run from the `third_party/boringssl` directory and to find the 52BoringSSL source code in `src/`. You should pass it a single argument: the name 53of the build system that you're using. If you don't use any of the supported 54build systems then you should augment `generate_build_files.py` with support 55for it. 56 57The script will pregenerate the intermediate files (see 58[BUILDING.md](/BUILDING.md) for details about which tools will need to be 59installed) and output helper files for that build system. It doesn't generate a 60complete build script, just file and test lists, which change often. For 61example, see the 62[file](https://code.google.com/p/chromium/codesearch#chromium/src/third_party/boringssl/BUILD.generated.gni) 63and 64[test](https://code.google.com/p/chromium/codesearch#chromium/src/third_party/boringssl/BUILD.generated_tests.gni) 65lists generated for GN in Chromium. 66 67Generally one checks in these generated files alongside the hand-written build 68files. Periodically an engineer updates the BoringSSL revision, regenerates 69these files and checks in the updated result. As an example, see how this is 70done [in Chromium](https://code.google.com/p/chromium/codesearch#chromium/src/third_party/boringssl/). 71 72## Defines 73 74BoringSSL does not present a lot of configurability in order to reduce the 75number of configurations that need to be tested. But there are a couple of 76\#defines that you may wish to set: 77 78`OPENSSL_NO_ASM` prevents the use of assembly code (although it's up to you to 79ensure that the build system doesn't link it in if you wish to reduce binary 80size). This will have a significant performance impact but can be useful if you 81wish to use tools like 82[AddressSanitizer](http://clang.llvm.org/docs/AddressSanitizer.html) that 83interact poorly with assembly code. 84 85`OPENSSL_SMALL` removes some code that is especially large at some performance 86cost. 87 88## Symbols 89 90You cannot link multiple versions of BoringSSL or OpenSSL into a single binary 91without dealing with symbol conflicts. If you are statically linking multiple 92versions together, there's not a lot that can be done because C doesn't have a 93module system. 94 95If you are using multiple versions in a single binary, in different shared 96objects, ensure you build BoringSSL with `-fvisibility=hidden` and do not 97export any of BoringSSL's symbols. This will prevent any collisions with other 98verisons that may be included in other shared objects. Note that this requires 99that all callers of BoringSSL APIs live in the same shared object as BoringSSL. 100 101If you require that BoringSSL APIs be used across shared object boundaries, 102continue to build with `-fvisibility=hidden` but define 103`BORINGSSL_SHARED_LIBRARY` in both BoringSSL and consumers. BoringSSL's own 104source files (but *not* consumers' source files) must also build with 105`BORINGSSL_IMPLEMENTATION` defined. This will export BoringSSL's public symbols 106in the resulting shared object while hiding private symbols. However note that, 107as with a static link, this precludes dynamically linking with another version 108of BoringSSL or OpenSSL. 109