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