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. This has
83been tested with version 10d of the NDK.
84
85Unpack the Android NDK somewhere and export `ANDROID_NDK` to point to the
86directory. Then make a build directory as above and run CMake like this:
87
88    cmake -DANDROID_ABI=armeabi-v7a \
89          -DCMAKE_TOOLCHAIN_FILE=../third_party/android-cmake/android.toolchain.cmake \
90          -DANDROID_NATIVE_API_LEVEL=16 \
91          -GNinja ..
92
93Once you've run that, Ninja should produce Android-compatible binaries.  You
94can replace `armeabi-v7a` in the above with `arm64-v8a` and use API level 21 or
95higher to build aarch64 binaries.
96
97For other options, see [android-cmake's documentation](./third_party/android-cmake/README.md).
98
99## Known Limitations on Windows
100
101  * Versions of CMake since 3.0.2 have a bug in its Ninja generator that causes
102    yasm to output warnings
103
104        yasm: warning: can open only one input file, only the last file will be processed
105
106    These warnings can be safely ignored. The cmake bug is
107    http://www.cmake.org/Bug/view.php?id=15253.
108
109  * CMake can generate Visual Studio projects, but the generated project files
110    don't have steps for assembling the assembly language source files, so they
111    currently cannot be used to build BoringSSL.
112
113## Embedded ARM
114
115ARM, unlike Intel, does not have an instruction that allows applications to
116discover the capabilities of the processor. Instead, the capability information
117has to be provided by the operating system somehow.
118
119BoringSSL will try to use `getauxval` to discover the capabilities and, failing
120that, will probe for NEON support by executing a NEON instruction and handling
121any illegal-instruction signal. But some environments don't support that sort
122of thing and, for them, it's possible to configure the CPU capabilities
123at compile time.
124
125If you define `OPENSSL_STATIC_ARMCAP` then you can define any of the following
126to enabling the corresponding ARM feature.
127
128  * `OPENSSL_STATIC_ARMCAP_NEON` or `__ARM_NEON__` (note that the latter is set by compilers when NEON support is enabled).
129  * `OPENSSL_STATIC_ARMCAP_AES`
130  * `OPENSSL_STATIC_ARMCAP_SHA1`
131  * `OPENSSL_STATIC_ARMCAP_SHA256`
132  * `OPENSSL_STATIC_ARMCAP_PMULL`
133
134Note that if a feature is enabled in this way, but not actually supported at
135run-time, BoringSSL will likely crash.
136
137## Assembling ARMv8 with Clang
138
139In order to support the ARMv8 crypto instructions, Clang requires that the
140architecture be `armv8-a+crypto`. However, setting that as a general build flag
141would allow the compiler to assume that crypto instructions are *always*
142supported, even without testing for them.
143
144It's possible to set the architecture in an assembly file using the `.arch`
145directive, but only very recent versions of Clang support this. If
146`BORINGSSL_CLANG_SUPPORTS_DOT_ARCH` is defined then `.arch` directives will be
147used with Clang, otherwise you may need to craft acceptable assembler flags.
148
149# Running tests
150
151There are two sets of tests: the C/C++ tests and the blackbox tests. For former
152are built by Ninja and can be run from the top-level directory with `go run
153util/all_tests.go`. The latter have to be run separately by running `go test`
154from within `ssl/test/runner`.
155
156Both sets of tests may also be run with `ninja -C build run_tests`, but CMake
1573.2 or later is required to avoid Ninja's output buffering.
158