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