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