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