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.12 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 * Compilers for C11 and C++14, or later, are required. On Windows, MSVC from 34 Visual Studio 2019 or later with Windows 10 SDK 2104 or later are 35 supported, but using the latest versions is recommended. Recent versions of 36 GCC (6.1+) and Clang should work on non-Windows platforms, and maybe on 37 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 cmake -GNinja -B build 52 ninja -C build 53 54Using Make (does not work on Windows): 55 56 cmake -B build 57 make -C build 58 59You usually don't need to run `cmake` again after changing `CMakeLists.txt` 60files because the build scripts will detect changes to them and rebuild 61themselves automatically. 62 63Note that the default build flags in the top-level `CMakeLists.txt` are for 64debugging—optimisation isn't enabled. Pass `-DCMAKE_BUILD_TYPE=Release` to 65`cmake` to configure a release build. 66 67If you want to cross-compile then there is an example toolchain file for 32-bit 68Intel in `util/`. Wipe out the build directory, run `cmake` like this: 69 70 cmake -B build -DCMAKE_TOOLCHAIN_FILE=../util/32-bit-toolchain.cmake -GNinja 71 72If you want to build as a shared library, pass `-DBUILD_SHARED_LIBS=1`. On 73Windows, where functions need to be tagged with `dllimport` when coming from a 74shared library, define `BORINGSSL_SHARED_LIBRARY` in any code which `#include`s 75the BoringSSL headers. 76 77In order to serve environments where code-size is important as well as those 78where performance is the overriding concern, `OPENSSL_SMALL` can be defined to 79remove some code that is especially large. 80 81See [CMake's documentation](https://cmake.org/cmake/help/v3.4/manual/cmake-variables.7.html) 82for other variables which may be used to configure the build. 83 84### Building for Android 85 86It's possible to build BoringSSL with the Android NDK using CMake. Recent 87versions of the NDK include a CMake toolchain file which works with CMake 3.6.0 88or later. This has been tested with version r16b of the NDK. 89 90Unpack the Android NDK somewhere and export `ANDROID_NDK` to point to the 91directory. Then run CMake like this: 92 93 cmake -DANDROID_ABI=armeabi-v7a \ 94 -DANDROID_PLATFORM=android-19 \ 95 -DCMAKE_TOOLCHAIN_FILE=${ANDROID_NDK}/build/cmake/android.toolchain.cmake \ 96 -GNinja -B build 97 98Once you've run that, Ninja should produce Android-compatible binaries. You 99can replace `armeabi-v7a` in the above with `arm64-v8a` and use API level 21 or 100higher to build aarch64 binaries. 101 102For other options, see the documentation in the toolchain file. 103 104To debug the resulting binaries on an Android device with `gdb`, run the 105commands below. Replace `ARCH` with the architecture of the target device, e.g. 106`arm` or `arm64`. 107 108 adb push ${ANDROID_NDK}/prebuilt/android-ARCH/gdbserver/gdbserver \ 109 /data/local/tmp 110 adb forward tcp:5039 tcp:5039 111 adb shell /data/local/tmp/gdbserver :5039 /path/on/device/to/binary 112 113Then run the following in a separate shell. Replace `HOST` with the OS and 114architecture of the host machine, e.g. `linux-x86_64`. 115 116 ${ANDROID_NDK}/prebuilt/HOST/bin/gdb 117 target remote :5039 # in gdb 118 119### Building for iOS 120 121To build for iOS, pass `-DCMAKE_OSX_SYSROOT=iphoneos` and 122`-DCMAKE_OSX_ARCHITECTURES=ARCH` to CMake, where `ARCH` is the desired 123architecture, matching values used in the `-arch` flag in Apple's toolchain. 124 125Passing multiple architectures for a multiple-architecture build is not 126supported. 127 128### Building with Prefixed Symbols 129 130BoringSSL's build system has experimental support for adding a custom prefix to 131all symbols. This can be useful when linking multiple versions of BoringSSL in 132the same project to avoid symbol conflicts. 133 134In order to build with prefixed symbols, the `BORINGSSL_PREFIX` CMake variable 135should specify the prefix to add to all symbols, and the 136`BORINGSSL_PREFIX_SYMBOLS` CMake variable should specify the path to a file 137which contains a list of symbols which should be prefixed (one per line; 138comments are supported with `#`). In other words, `cmake -B build 139-DBORINGSSL_PREFIX=MY_CUSTOM_PREFIX 140-DBORINGSSL_PREFIX_SYMBOLS=/path/to/symbols.txt` will configure the build to add 141the prefix `MY_CUSTOM_PREFIX` to all of the symbols listed in 142`/path/to/symbols.txt`. 143 144It is currently the caller's responsibility to create and maintain the list of 145symbols to be prefixed. Alternatively, `util/read_symbols.go` reads the list of 146exported symbols from a `.a` file, and can be used in a build script to generate 147the symbol list on the fly (by building without prefixing, using 148`read_symbols.go` to construct a symbol list, and then building again with 149prefixing). 150 151This mechanism is under development and may change over time. Please contact the 152BoringSSL maintainers if making use of it. 153 154## Known Limitations on Windows 155 156 * CMake can generate Visual Studio projects, but the generated project files 157 don't have steps for assembling the assembly language source files, so they 158 currently cannot be used to build BoringSSL. 159 160## ARM CPU Capabilities 161 162ARM, unlike Intel, does not have a userspace instruction that allows 163applications to discover the capabilities of the processor. Instead, the 164capability information has to be provided by a combination of compile-time 165information and the operating system. 166 167BoringSSL determines capabilities at compile-time based on `__ARM_NEON`, 168`__ARM_FEATURE_AES`, and other preprocessor symbols defined in 169[Arm C Language Extensions (ACLE)](https://developer.arm.com/architectures/system-architectures/software-standards/acle). 170These values are usually controlled by the `-march` flag. You can also define 171any of the following to enable the corresponding ARM feature, but using the ACLE 172symbols via `-march` is recommended. 173 174 * `OPENSSL_STATIC_ARMCAP_NEON` 175 * `OPENSSL_STATIC_ARMCAP_AES` 176 * `OPENSSL_STATIC_ARMCAP_SHA1` 177 * `OPENSSL_STATIC_ARMCAP_SHA256` 178 * `OPENSSL_STATIC_ARMCAP_PMULL` 179 180The resulting binary will assume all such features are always present. This can 181reduce code size, by allowing the compiler to omit fallbacks. However, if the 182feature is not actually supported at runtime, BoringSSL will likely crash. 183 184BoringSSL will additionally query the operating system at runtime for additional 185features, e.g. with `getauxval` on Linux. This allows a single binary to use 186newer instructions when present, but still function on CPUs without them. But 187some environments don't support runtime queries. If building for those, define 188`OPENSSL_STATIC_ARMCAP` to limit BoringSSL to compile-time capabilities. If not 189defined, the target operating system must be known to BoringSSL. 190 191## Binary Size 192 193The implementations of some algorithms require a trade-off between binary size 194and performance. For instance, BoringSSL's fastest P-256 implementation uses a 195148 KiB pre-computed table. To optimize instead for binary size, pass 196`-DOPENSSL_SMALL=1` to CMake or define the `OPENSSL_SMALL` preprocessor symbol. 197 198# Running Tests 199 200There are two sets of tests: the C/C++ tests and the blackbox tests. For former 201are built by Ninja and can be run from the top-level directory with `go run 202util/all_tests.go`. The latter have to be run separately by running `go test` 203from within `ssl/test/runner`. 204 205Both sets of tests may also be run with `ninja -C build run_tests`, but CMake 2063.2 or later is required to avoid Ninja's output buffering. 207