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