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://gn.googlesource.com/gn/+/master/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