• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Building BoringSSL
2
3## Build Prerequisites
4
5The standalone CMake build is primarily intended for developers. If embedding
6BoringSSL into another project with a pre-existing build system, see
7[INCORPORATING.md](/INCORPORATING.md).
8
9Unless otherwise noted, build tools must at most five years old, matching
10[Abseil guidelines](https://abseil.io/about/compatibility). If in doubt, use the
11most recent stable version of each tool.
12
13  * [CMake](https://cmake.org/download/) 3.0 or later is required.
14
15  * A recent version of Perl is required. On Windows,
16    [Active State Perl](http://www.activestate.com/activeperl/) has been
17    reported to work, as has MSYS Perl.
18    [Strawberry Perl](http://strawberryperl.com/) also works but it adds GCC
19    to `PATH`, which can confuse some build tools when identifying the compiler
20    (removing `C:\Strawberry\c\bin` from `PATH` should resolve any problems).
21    If Perl is not found by CMake, it may be configured explicitly by setting
22    `PERL_EXECUTABLE`.
23
24  * Building with [Ninja](https://ninja-build.org/) instead of Make is
25    recommended, because it makes builds faster. On Windows, CMake's Visual
26    Studio generator may also work, but it not tested regularly and requires
27    recent versions of CMake for assembly support.
28
29  * On Windows only, [NASM](https://www.nasm.us/) is required. If not found
30    by CMake, it may be configured explicitly by setting
31    `CMAKE_ASM_NASM_COMPILER`.
32
33  * C and C++ compilers with C++11 support are required. On Windows, MSVC 14
34    (Visual Studio 2015) or later with Platform SDK 8.1 or later are supported.
35    Recent versions of GCC (4.8+) and Clang should work on non-Windows
36    platforms, and maybe on Windows too.
37
38  * The most recent stable version of [Go](https://golang.org/dl/) is required.
39    Note Go is exempt from the five year support window. If not found by CMake,
40    the go executable may be configured explicitly by setting `GO_EXECUTABLE`.
41
42  * On x86_64 Linux, the tests have an optional
43    [libunwind](https://www.nongnu.org/libunwind/) dependency to test the
44    assembly more thoroughly.
45
46## Building
47
48Using Ninja (note the 'N' is capitalized in the cmake invocation):
49
50    mkdir build
51    cd build
52    cmake -GNinja ..
53    ninja
54
55Using Make (does not work on Windows):
56
57    mkdir build
58    cd build
59    cmake ..
60    make
61
62You usually don't need to run `cmake` again after changing `CMakeLists.txt`
63files because the build scripts will detect changes to them and rebuild
64themselves automatically.
65
66Note that the default build flags in the top-level `CMakeLists.txt` are for
67debugging—optimisation isn't enabled. Pass `-DCMAKE_BUILD_TYPE=Release` to
68`cmake` to configure a release build.
69
70If you want to cross-compile then there is an example toolchain file for 32-bit
71Intel in `util/`. Wipe out the build directory, recreate it and run `cmake` like
72this:
73
74    cmake -DCMAKE_TOOLCHAIN_FILE=../util/32-bit-toolchain.cmake -GNinja ..
75
76If you want to build as a shared library, pass `-DBUILD_SHARED_LIBS=1`. On
77Windows, where functions need to be tagged with `dllimport` when coming from a
78shared library, define `BORINGSSL_SHARED_LIBRARY` in any code which `#include`s
79the BoringSSL headers.
80
81In order to serve environments where code-size is important as well as those
82where performance is the overriding concern, `OPENSSL_SMALL` can be defined to
83remove some code that is especially large.
84
85See [CMake's documentation](https://cmake.org/cmake/help/v3.4/manual/cmake-variables.7.html)
86for other variables which may be used to configure the build.
87
88### Building for Android
89
90It's possible to build BoringSSL with the Android NDK using CMake. Recent
91versions of the NDK include a CMake toolchain file which works with CMake 3.6.0
92or later. This has been tested with version r16b of the NDK.
93
94Unpack the Android NDK somewhere and export `ANDROID_NDK` to point to the
95directory. Then make a build directory as above and run CMake like this:
96
97    cmake -DANDROID_ABI=armeabi-v7a \
98          -DCMAKE_TOOLCHAIN_FILE=${ANDROID_NDK}/build/cmake/android.toolchain.cmake \
99          -DANDROID_NATIVE_API_LEVEL=16 \
100          -GNinja ..
101
102Once you've run that, Ninja should produce Android-compatible binaries.  You
103can replace `armeabi-v7a` in the above with `arm64-v8a` and use API level 21 or
104higher to build aarch64 binaries.
105
106For other options, see the documentation in the toolchain file.
107
108To debug the resulting binaries on an Android device with `gdb`, run the
109commands below. Replace `ARCH` with the architecture of the target device, e.g.
110`arm` or `arm64`.
111
112    adb push ${ANDROID_NDK}/prebuilt/android-ARCH/gdbserver/gdbserver \
113        /data/local/tmp
114    adb forward tcp:5039 tcp:5039
115    adb shell /data/local/tmp/gdbserver :5039 /path/on/device/to/binary
116
117Then run the following in a separate shell. Replace `HOST` with the OS and
118architecture of the host machine, e.g. `linux-x86_64`.
119
120    ${ANDROID_NDK}/prebuilt/HOST/bin/gdb
121    target remote :5039  # in gdb
122
123### Building for iOS
124
125To build for iOS, pass `-DCMAKE_OSX_SYSROOT=iphoneos` and
126`-DCMAKE_OSX_ARCHITECTURES=ARCH` to CMake, where `ARCH` is the desired
127architecture, matching values used in the `-arch` flag in Apple's toolchain.
128
129Passing multiple architectures for a multiple-architecture build is not
130supported.
131
132### Building with Prefixed Symbols
133
134BoringSSL's build system has experimental support for adding a custom prefix to
135all symbols. This can be useful when linking multiple versions of BoringSSL in
136the same project to avoid symbol conflicts.
137
138In order to build with prefixed symbols, the `BORINGSSL_PREFIX` CMake variable
139should specify the prefix to add to all symbols, and the
140`BORINGSSL_PREFIX_SYMBOLS` CMake variable should specify the path to a file
141which contains a list of symbols which should be prefixed (one per line;
142comments are supported with `#`). In other words, `cmake ..
143-DBORINGSSL_PREFIX=MY_CUSTOM_PREFIX
144-DBORINGSSL_PREFIX_SYMBOLS=/path/to/symbols.txt` will configure the build to add
145the prefix `MY_CUSTOM_PREFIX` to all of the symbols listed in
146`/path/to/symbols.txt`.
147
148It is currently the caller's responsibility to create and maintain the list of
149symbols to be prefixed. Alternatively, `util/read_symbols.go` reads the list of
150exported symbols from a `.a` file, and can be used in a build script to generate
151the symbol list on the fly (by building without prefixing, using
152`read_symbols.go` to construct a symbol list, and then building again with
153prefixing).
154
155This mechanism is under development and may change over time. Please contact the
156BoringSSL maintainers if making use of it.
157
158## Known Limitations on Windows
159
160  * Versions of CMake since 3.0.2 have a bug in its Ninja generator that causes
161    yasm to output warnings
162
163        yasm: warning: can open only one input file, only the last file will be processed
164
165    These warnings can be safely ignored. The cmake bug is
166    http://www.cmake.org/Bug/view.php?id=15253.
167
168  * CMake can generate Visual Studio projects, but the generated project files
169    don't have steps for assembling the assembly language source files, so they
170    currently cannot be used to build BoringSSL.
171
172## Embedded ARM
173
174ARM, unlike Intel, does not have an instruction that allows applications to
175discover the capabilities of the processor. Instead, the capability information
176has to be provided by the operating system somehow.
177
178By default, on Linux-based systems, BoringSSL will try to use `getauxval` and
179`/proc` to discover the capabilities. But some environments don't support that
180sort of thing and, for them, it's possible to configure the CPU capabilities at
181compile time.
182
183On iOS or builds which define `OPENSSL_STATIC_ARMCAP`, features will be
184determined based on the `__ARM_NEON__` and `__ARM_FEATURE_CRYPTO` preprocessor
185symbols reported by the compiler. These values are usually controlled by the
186`-march` flag. You can also define any of the following to enable the
187corresponding ARM feature.
188
189  * `OPENSSL_STATIC_ARMCAP_NEON`
190  * `OPENSSL_STATIC_ARMCAP_AES`
191  * `OPENSSL_STATIC_ARMCAP_SHA1`
192  * `OPENSSL_STATIC_ARMCAP_SHA256`
193  * `OPENSSL_STATIC_ARMCAP_PMULL`
194
195Note that if a feature is enabled in this way, but not actually supported at
196run-time, BoringSSL will likely crash.
197
198## Binary Size
199
200The implementations of some algorithms require a trade-off between binary size
201and performance. For instance, BoringSSL's fastest P-256 implementation uses a
202148 KiB pre-computed table. To optimize instead for binary size, pass
203`-DOPENSSL_SMALL=1` to CMake or define the `OPENSSL_SMALL` preprocessor symbol.
204
205# Running Tests
206
207There are two sets of tests: the C/C++ tests and the blackbox tests. For former
208are built by Ninja and can be run from the top-level directory with `go run
209util/all_tests.go`. The latter have to be run separately by running `go test`
210from within `ssl/test/runner`.
211
212Both sets of tests may also be run with `ninja -C build run_tests`, but CMake
2133.2 or later is required to avoid Ninja's output buffering.
214