1# Building BoringSSL
2
3## Build Prerequisites
4
5  * [CMake](http://www.cmake.org/download/) 2.8.8 or later is required.
6
7  * Perl 5.6.1 or later is required. On Windows,
8    [Strawberry Perl](http://strawberryperl.com/) and MSYS Perl have both been
9    reported to work. If not found by CMake, it may be configured explicitly by
10    setting `PERL_EXECUTABLE`.
11
12  * On Windows you currently must use [Ninja](https://martine.github.io/ninja/)
13    to build; on other platforms, it is not required, but recommended, because
14    it makes builds faster.
15
16  * If you need to build Ninja from source, then a recent version of
17    [Python](https://www.python.org/downloads/) is required (Python 2.7.5 works).
18
19  * On Windows only, [Yasm](http://yasm.tortall.net/) is required. If not found
20    by CMake, it may be configured explicitly by setting
21    `CMAKE_ASM_NASM_COMPILER`.
22
23  * A C compiler is required. On Windows, MSVC 12 (Visual Studio 2013) or later
24    with Platform SDK 8.1 or later are supported. Recent versions of GCC and
25    Clang should work on non-Windows platforms, and maybe on Windows too.
26
27  * [Go](https://golang.org/dl/) is required. If not found by CMake, the go
28    executable may be configured explicitly by setting `GO_EXECUTABLE`.
29
30  * If you change crypto/chacha/chacha\_vec.c, you will need the
31    arm-linux-gnueabihf-gcc compiler:
32
33    ```
34    wget https://releases.linaro.org/14.11/components/toolchain/binaries/arm-linux-gnueabihf/gcc-linaro-4.9-2014.11-x86_64_arm-linux-gnueabihf.tar.xz && \
35    echo bc4ca2ced084d2dc12424815a4442e19cb1422db87068830305d90075feb1a3b  gcc-linaro-4.9-2014.11-x86_64_arm-linux-gnueabihf.tar.xz | sha256sum -c && \
36    tar xf gcc-linaro-4.9-2014.11-x86_64_arm-linux-gnueabihf.tar.xz && \
37    sudo mv gcc-linaro-4.9-2014.11-x86_64_arm-linux-gnueabihf /opt/
38    ```
39
40## Building
41
42Using Ninja (note the 'N' is capitalized in the cmake invocation):
43
44    mkdir build
45    cd build
46    cmake -GNinja ..
47    ninja
48
49Using Make (does not work on Windows):
50
51    mkdir build
52    cd build
53    cmake ..
54    make
55
56You usually don't need to run `cmake` again after changing `CMakeLists.txt`
57files because the build scripts will detect changes to them and rebuild
58themselves automatically.
59
60Note that the default build flags in the top-level `CMakeLists.txt` are for
61debugging—optimisation isn't enabled.
62
63If you want to cross-compile then there is an example toolchain file for 32-bit
64Intel in `util/`. Wipe out the build directory, recreate it and run `cmake` like
65this:
66
67    cmake -DCMAKE_TOOLCHAIN_FILE=../util/32-bit-toolchain.cmake -GNinja ..
68
69If you want to build as a shared library, pass `-DBUILD_SHARED_LIBS=1`. On
70Windows, where functions need to be tagged with `dllimport` when coming from a
71shared library, define `BORINGSSL_SHARED_LIBRARY` in any code which `#include`s
72the BoringSSL headers.
73
74In order to serve environments where code-size is important as well as those
75where performance is the overriding concern, `OPENSSL_SMALL` can be defined to
76remove some code that is especially large.
77
78### Building for Android
79
80It's possible to build BoringSSL with the Android NDK using CMake. This has
81been tested with version 10d of the NDK.
82
83Unpack the Android NDK somewhere and export `ANDROID_NDK` to point to the
84directory. Clone https://github.com/taka-no-me/android-cmake into `util/`.  Then
85make a build directory as above and run CMake *twice* like this:
86
87    cmake -DANDROID_NATIVE_API_LEVEL=android-9 \
88          -DANDROID_ABI=armeabi-v7a \
89          -DCMAKE_TOOLCHAIN_FILE=../util/android-cmake/android.toolchain.cmake \
90          -DANDROID_NATIVE_API_LEVEL=16 \
91          -GNinja ..
92
93Once you've run that twice, Ninja should produce Android-compatible binaries.
94You can replace `armeabi-v7a` in the above with `arm64-v8a` to build aarch64
95binaries.
96
97## Known Limitations on Windows
98
99  * Versions of CMake since 3.0.2 have a bug in its Ninja generator that causes
100    yasm to output warnings
101
102        yasm: warning: can open only one input file, only the last file will be processed
103
104    These warnings can be safely ignored. The cmake bug is
105    http://www.cmake.org/Bug/view.php?id=15253.
106
107  * CMake can generate Visual Studio projects, but the generated project files
108    don't have steps for assembling the assembly language source files, so they
109    currently cannot be used to build BoringSSL.
110
111## Embedded ARM
112
113ARM, unlike Intel, does not have an instruction that allows applications to
114discover the capabilities of the processor. Instead, the capability information
115has to be provided by the operating system somehow.
116
117BoringSSL will try to use `getauxval` to discover the capabilities and, failing
118that, will probe for NEON support by executing a NEON instruction and handling
119any illegal-instruction signal. But some environments don't support that sort
120of thing and, for them, it's possible to configure the CPU capabilities
121at compile time.
122
123If you define `OPENSSL_STATIC_ARMCAP` then you can define any of the following
124to enabling the corresponding ARM feature.
125
126  * `OPENSSL_STATIC_ARMCAP_NEON` or `__ARM_NEON__` (note that the latter is set by compilers when NEON support is enabled).
127  * `OPENSSL_STATIC_ARMCAP_AES`
128  * `OPENSSL_STATIC_ARMCAP_SHA1`
129  * `OPENSSL_STATIC_ARMCAP_SHA256`
130  * `OPENSSL_STATIC_ARMCAP_PMULL`
131
132Note that if a feature is enabled in this way, but not actually supported at
133run-time, BoringSSL will likely crash.
134
135# Running tests
136
137There are two sets of tests: the C/C++ tests and the blackbox tests. For former
138are built by Ninja and can be run from the top-level directory with `go run
139util/all_tests.go`. The latter have to be run separately by running `go test`
140from within `ssl/test/runner`.
141
142Both sets of tests may also be run with `ninja -C build run_tests`, but CMake
1433.2 or later is required to avoid Ninja's output buffering.
144