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