• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Building BoringSSL
2
3## Build Prerequisites
4
5  * [CMake](https://cmake.org/download/) 2.8.11 or later is required.
6
7  * Perl 5.6.1 or later is required. On Windows,
8    [Active State Perl](http://www.activestate.com/activeperl/) has been
9    reported to work, as has MSYS Perl.
10    [Strawberry Perl](http://strawberryperl.com/) also works but it adds GCC
11    to `PATH`, which can confuse some build tools when identifying the compiler
12    (removing `C:\Strawberry\c\bin` from `PATH` should resolve any problems).
13    If Perl is not found by CMake, it may be configured explicitly by setting
14    `PERL_EXECUTABLE`.
15
16  * On Windows you currently must use [Ninja](https://ninja-build.org/)
17    to build; on other platforms, it is not required, but recommended, because
18    it makes builds faster.
19
20  * If you need to build Ninja from source, then a recent version of
21    [Python](https://www.python.org/downloads/) is required (Python 2.7.5 works).
22
23  * On Windows only, [Yasm](http://yasm.tortall.net/) is required. If not found
24    by CMake, it may be configured explicitly by setting
25    `CMAKE_ASM_NASM_COMPILER`.
26
27  * A C compiler is required. On Windows, MSVC 14 (Visual Studio 2015) or later
28    with Platform SDK 8.1 or later are supported. Recent versions of GCC (4.8+)
29    and Clang should work on non-Windows platforms, and maybe on Windows too.
30    To build the tests, you also need a C++ compiler with C++11 support.
31
32  * [Go](https://golang.org/dl/) is required. If not found by CMake, the go
33    executable may be configured explicitly by setting `GO_EXECUTABLE`.
34
35  * To build the x86 and x86\_64 assembly, your assembler must support AVX2
36    instructions and MOVBE. If using GNU binutils, you must have 2.22 or later
37
38## Building
39
40Using Ninja (note the 'N' is capitalized in the cmake invocation):
41
42    mkdir build
43    cd build
44    cmake -GNinja ..
45    ninja
46
47Using Make (does not work on Windows):
48
49    mkdir build
50    cd build
51    cmake ..
52    make
53
54You usually don't need to run `cmake` again after changing `CMakeLists.txt`
55files because the build scripts will detect changes to them and rebuild
56themselves automatically.
57
58Note that the default build flags in the top-level `CMakeLists.txt` are for
59debugging—optimisation isn't enabled. Pass `-DCMAKE_BUILD_TYPE=Release` to
60`cmake` to configure a release build.
61
62If you want to cross-compile then there is an example toolchain file for 32-bit
63Intel in `util/`. Wipe out the build directory, recreate it and run `cmake` like
64this:
65
66    cmake -DCMAKE_TOOLCHAIN_FILE=../util/32-bit-toolchain.cmake -GNinja ..
67
68If you want to build as a shared library, pass `-DBUILD_SHARED_LIBS=1`. On
69Windows, where functions need to be tagged with `dllimport` when coming from a
70shared library, define `BORINGSSL_SHARED_LIBRARY` in any code which `#include`s
71the BoringSSL headers.
72
73In order to serve environments where code-size is important as well as those
74where performance is the overriding concern, `OPENSSL_SMALL` can be defined to
75remove some code that is especially large.
76
77See [CMake's documentation](https://cmake.org/cmake/help/v3.4/manual/cmake-variables.7.html)
78for other variables which may be used to configure the build.
79
80### Building for Android
81
82It's possible to build BoringSSL with the Android NDK using CMake. Recent
83versions of the NDK include a CMake toolchain file which works with CMake 3.6.0
84or later. This has been tested with version r16b of the NDK.
85
86Unpack the Android NDK somewhere and export `ANDROID_NDK` to point to the
87directory. Then make a build directory as above and run CMake like this:
88
89    cmake -DANDROID_ABI=armeabi-v7a \
90          -DCMAKE_TOOLCHAIN_FILE=${ANDROID_NDK}/build/cmake/android.toolchain.cmake \
91          -DANDROID_NATIVE_API_LEVEL=16 \
92          -GNinja ..
93
94Once you've run that, Ninja should produce Android-compatible binaries.  You
95can replace `armeabi-v7a` in the above with `arm64-v8a` and use API level 21 or
96higher to build aarch64 binaries.
97
98For older NDK versions, BoringSSL ships a third-party CMake toolchain file. Use
99`../third_party/android-cmake/android.toolchain.cmake` for
100`CMAKE_TOOLCHAIN_FILE` instead.
101
102For other options, see the documentation in the toolchain file.
103
104### Building for iOS
105
106To build for iOS, pass `-DCMAKE_OSX_SYSROOT=iphoneos` and
107`-DCMAKE_OSX_ARCHITECTURES=ARCH` to CMake, where `ARCH` is the desired
108architecture, matching values used in the `-arch` flag in Apple's toolchain.
109
110Passing multiple architectures for a multiple-architecture build is not
111supported.
112
113## Known Limitations on Windows
114
115  * Versions of CMake since 3.0.2 have a bug in its Ninja generator that causes
116    yasm to output warnings
117
118        yasm: warning: can open only one input file, only the last file will be processed
119
120    These warnings can be safely ignored. The cmake bug is
121    http://www.cmake.org/Bug/view.php?id=15253.
122
123  * CMake can generate Visual Studio projects, but the generated project files
124    don't have steps for assembling the assembly language source files, so they
125    currently cannot be used to build BoringSSL.
126
127## Embedded ARM
128
129ARM, unlike Intel, does not have an instruction that allows applications to
130discover the capabilities of the processor. Instead, the capability information
131has to be provided by the operating system somehow.
132
133By default, on Linux-based systems, BoringSSL will try to use `getauxval` and
134`/proc` to discover the capabilities. But some environments don't support that
135sort of thing and, for them, it's possible to configure the CPU capabilities at
136compile time.
137
138On iOS or builds which define `OPENSSL_STATIC_ARMCAP`, features will be
139determined based on the `__ARM_NEON__` and `__ARM_FEATURE_CRYPTO` preprocessor
140symbols reported by the compiler. These values are usually controlled by the
141`-march` flag. You can also define any of the following to enable the
142corresponding ARM feature.
143
144  * `OPENSSL_STATIC_ARMCAP_NEON`
145  * `OPENSSL_STATIC_ARMCAP_AES`
146  * `OPENSSL_STATIC_ARMCAP_SHA1`
147  * `OPENSSL_STATIC_ARMCAP_SHA256`
148  * `OPENSSL_STATIC_ARMCAP_PMULL`
149
150Note that if a feature is enabled in this way, but not actually supported at
151run-time, BoringSSL will likely crash.
152
153# Running tests
154
155There are two sets of tests: the C/C++ tests and the blackbox tests. For former
156are built by Ninja and can be run from the top-level directory with `go run
157util/all_tests.go`. The latter have to be run separately by running `go test`
158from within `ssl/test/runner`.
159
160Both sets of tests may also be run with `ninja -C build run_tests`, but CMake
1613.2 or later is required to avoid Ninja's output buffering.
162