1 # Building BoringSSL 2 3 ## Build Prerequisites 4 5 The standalone CMake build is primarily intended for developers. If embedding 6 BoringSSL into another project with a pre-existing build system, see 7 [INCORPORATING.md](/INCORPORATING.md). 8 9 Unless otherwise noted, build tools must at most five years old, matching 10 [Abseil guidelines](https://abseil.io/about/compatibility). If in doubt, use the 11 most 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 49 Using Ninja (note the 'N' is capitalized in the cmake invocation): 50 51 mkdir build 52 cd build 53 cmake -GNinja .. 54 ninja 55 56 Using Make (does not work on Windows): 57 58 mkdir build 59 cd build 60 cmake .. 61 make 62 63 You usually don't need to run `cmake` again after changing `CMakeLists.txt` 64 files because the build scripts will detect changes to them and rebuild 65 themselves automatically. 66 67 Note that the default build flags in the top-level `CMakeLists.txt` are for 68 debuggingoptimisation isn't enabled. Pass `-DCMAKE_BUILD_TYPE=Release` to 69 `cmake` to configure a release build. 70 71 If you want to cross-compile then there is an example toolchain file for 32-bit 72 Intel in `util/`. Wipe out the build directory, recreate it and run `cmake` like 73 this: 74 75 cmake -DCMAKE_TOOLCHAIN_FILE=../util/32-bit-toolchain.cmake -GNinja .. 76 77 If you want to build as a shared library, pass `-DBUILD_SHARED_LIBS=1`. On 78 Windows, where functions need to be tagged with `dllimport` when coming from a 79 shared library, define `BORINGSSL_SHARED_LIBRARY` in any code which `#include`s 80 the BoringSSL headers. 81 82 In order to serve environments where code-size is important as well as those 83 where performance is the overriding concern, `OPENSSL_SMALL` can be defined to 84 remove some code that is especially large. 85 86 See [CMake's documentation](https://cmake.org/cmake/help/v3.4/manual/cmake-variables.7.html) 87 for other variables which may be used to configure the build. 88 89 ### Building for Android 90 91 It's possible to build BoringSSL with the Android NDK using CMake. Recent 92 versions of the NDK include a CMake toolchain file which works with CMake 3.6.0 93 or later. This has been tested with version r16b of the NDK. 94 95 Unpack the Android NDK somewhere and export `ANDROID_NDK` to point to the 96 directory. 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 103 Once you've run that, Ninja should produce Android-compatible binaries. You 104 can replace `armeabi-v7a` in the above with `arm64-v8a` and use API level 21 or 105 higher to build aarch64 binaries. 106 107 For other options, see the documentation in the toolchain file. 108 109 To debug the resulting binaries on an Android device with `gdb`, run the 110 commands 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 118 Then run the following in a separate shell. Replace `HOST` with the OS and 119 architecture 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 126 To build for iOS, pass `-DCMAKE_OSX_SYSROOT=iphoneos` and 127 `-DCMAKE_OSX_ARCHITECTURES=ARCH` to CMake, where `ARCH` is the desired 128 architecture, matching values used in the `-arch` flag in Apple's toolchain. 129 130 Passing multiple architectures for a multiple-architecture build is not 131 supported. 132 133 ### Building with Prefixed Symbols 134 135 BoringSSL's build system has experimental support for adding a custom prefix to 136 all symbols. This can be useful when linking multiple versions of BoringSSL in 137 the same project to avoid symbol conflicts. 138 139 In order to build with prefixed symbols, the `BORINGSSL_PREFIX` CMake variable 140 should specify the prefix to add to all symbols, and the 141 `BORINGSSL_PREFIX_SYMBOLS` CMake variable should specify the path to a file 142 which contains a list of symbols which should be prefixed (one per line; 143 comments 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 146 the prefix `MY_CUSTOM_PREFIX` to all of the symbols listed in 147 `/path/to/symbols.txt`. 148 149 It is currently the caller's responsibility to create and maintain the list of 150 symbols to be prefixed. Alternatively, `util/read_symbols.go` reads the list of 151 exported symbols from a `.a` file, and can be used in a build script to generate 152 the symbol list on the fly (by building without prefixing, using 153 `read_symbols.go` to construct a symbol list, and then building again with 154 prefixing). 155 156 This mechanism is under development and may change over time. Please contact the 157 BoringSSL 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 175 ARM, unlike Intel, does not have an instruction that allows applications to 176 discover the capabilities of the processor. Instead, the capability information 177 has to be provided by the operating system somehow. 178 179 By 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 181 sort of thing and, for them, it's possible to configure the CPU capabilities at 182 compile time. 183 184 On iOS or builds which define `OPENSSL_STATIC_ARMCAP`, features will be 185 determined based on the `__ARM_NEON__` and `__ARM_FEATURE_CRYPTO` preprocessor 186 symbols 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 188 corresponding 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 196 Note that if a feature is enabled in this way, but not actually supported at 197 run-time, BoringSSL will likely crash. 198 199 ## Binary Size 200 201 The implementations of some algorithms require a trade-off between binary size 202 and performance. For instance, BoringSSL's fastest P-256 implementation uses a 203 148 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 208 There are two sets of tests: the C/C++ tests and the blackbox tests. For former 209 are built by Ninja and can be run from the top-level directory with `go run 210 util/all_tests.go`. The latter have to be run separately by running `go test` 211 from within `ssl/test/runner`. 212 213 Both sets of tests may also be run with `ninja -C build run_tests`, but CMake 214 3.2 or later is required to avoid Ninja's output buffering. 215
