1# Building BoringSSL 2 3## Checking out BoringSSL 4 5 git clone "https://boringssl.googlesource.com/boringssl" 6 7## Build Prerequisites 8 9The standalone CMake build is primarily intended for developers. If embedding 10BoringSSL into another project with a pre-existing build system, see 11[INCORPORATING.md](./INCORPORATING.md). 12 13Unless otherwise noted, build tools must at most five years old, matching 14[Abseil guidelines](https://abseil.io/about/compatibility). If in doubt, use the 15most recent stable version of each tool. 16 17 * [CMake](https://cmake.org/download/) 3.12 or later is required. 18 19 * Building with [Ninja](https://ninja-build.org/) instead of Make is 20 recommended, because it makes builds faster. On Windows, CMake's Visual 21 Studio generator may also work, but it not tested regularly and requires 22 recent versions of CMake for assembly support. 23 24 * On Windows only, [NASM](https://www.nasm.us/) is required. If not found 25 by CMake, it may be configured explicitly by setting 26 `CMAKE_ASM_NASM_COMPILER`. 27 28 * Compilers for C11 and C++14, or later, are required. On Windows, MSVC from 29 Visual Studio 2019 or later with Windows 10 SDK 2104 or later are 30 supported, but using the latest versions is recommended. Recent versions of 31 GCC (6.1+) and Clang should work on non-Windows platforms, and maybe on 32 Windows too. 33 34## Building 35 36Using Ninja (note the 'N' is capitalized in the cmake invocation): 37 38 cmake -GNinja -B build 39 ninja -C build 40 41Using Make (does not work on Windows): 42 43 cmake -B build 44 make -C build 45 46This produces a debug build by default. Optimisation isn't enabled, and debug 47assertions are included. Pass `-DCMAKE_BUILD_TYPE=Release` to `cmake` to 48configure a release build: 49 50 cmake -GNinja -B build -DCMAKE_BUILD_TYPE=Release 51 ninja -C build 52 53If you want to cross-compile then there is an example toolchain file for 32-bit 54Intel in `util/`. Wipe out the build directory, run `cmake` like this: 55 56 cmake -B build -DCMAKE_TOOLCHAIN_FILE=../util/32-bit-toolchain.cmake -GNinja 57 58If you want to build as a shared library, pass `-DBUILD_SHARED_LIBS=1`. On 59Windows, where functions need to be tagged with `dllimport` when coming from a 60shared library, define `BORINGSSL_SHARED_LIBRARY` in any code which `#include`s 61the BoringSSL headers. 62 63In order to serve environments where code-size is important as well as those 64where performance is the overriding concern, `OPENSSL_SMALL` can be defined to 65remove some code that is especially large. 66 67See [CMake's documentation](https://cmake.org/cmake/help/v3.4/manual/cmake-variables.7.html) 68for other variables which may be used to configure the build. 69 70You usually don't need to run `cmake` again after changing `CMakeLists.txt` 71files because the build scripts will detect changes to them and rebuild 72themselves automatically. 73 74### Building for Android 75 76It's possible to build BoringSSL with the Android NDK using CMake. Recent 77versions of the NDK include a CMake toolchain file which works with CMake 3.6.0 78or later. This has been tested with version r16b of the NDK. 79 80Unpack the Android NDK somewhere and export `ANDROID_NDK` to point to the 81directory. Then run CMake like this: 82 83 cmake -DANDROID_ABI=armeabi-v7a \ 84 -DANDROID_PLATFORM=android-19 \ 85 -DCMAKE_TOOLCHAIN_FILE=${ANDROID_NDK}/build/cmake/android.toolchain.cmake \ 86 -GNinja -B build 87 88Once you've run that, Ninja should produce Android-compatible binaries. You 89can replace `armeabi-v7a` in the above with `arm64-v8a` and use API level 21 or 90higher to build aarch64 binaries. 91 92For other options, see the documentation in the toolchain file. 93 94To debug the resulting binaries on an Android device with `gdb`, run the 95commands below. Replace `ARCH` with the architecture of the target device, e.g. 96`arm` or `arm64`. 97 98 adb push ${ANDROID_NDK}/prebuilt/android-ARCH/gdbserver/gdbserver \ 99 /data/local/tmp 100 adb forward tcp:5039 tcp:5039 101 adb shell /data/local/tmp/gdbserver :5039 /path/on/device/to/binary 102 103Then run the following in a separate shell. Replace `HOST` with the OS and 104architecture of the host machine, e.g. `linux-x86_64`. 105 106 ${ANDROID_NDK}/prebuilt/HOST/bin/gdb 107 target remote :5039 # in gdb 108 109### Building for iOS 110 111To build for iOS, pass `-DCMAKE_OSX_SYSROOT=iphoneos` and 112`-DCMAKE_OSX_ARCHITECTURES=ARCH` to CMake, where `ARCH` is the desired 113architecture, matching values used in the `-arch` flag in Apple's toolchain. 114 115Passing multiple architectures for a multiple-architecture build is not 116supported. 117 118### Building with Prefixed Symbols 119 120BoringSSL's build system has experimental support for adding a custom prefix to 121all symbols. This can be useful when linking multiple versions of BoringSSL in 122the same project to avoid symbol conflicts. Symbol prefixing requires the most 123recent stable version of [Go](https://go.dev/). 124 125In order to build with prefixed symbols, the `BORINGSSL_PREFIX` CMake variable 126should specify the prefix to add to all symbols, and the 127`BORINGSSL_PREFIX_SYMBOLS` CMake variable should specify the path to a file 128which contains a list of symbols which should be prefixed (one per line; 129comments are supported with `#`). In other words, `cmake -B build 130-DBORINGSSL_PREFIX=MY_CUSTOM_PREFIX 131-DBORINGSSL_PREFIX_SYMBOLS=/path/to/symbols.txt` will configure the build to add 132the prefix `MY_CUSTOM_PREFIX` to all of the symbols listed in 133`/path/to/symbols.txt`. 134 135It is currently the caller's responsibility to create and maintain the list of 136symbols to be prefixed. Alternatively, `util/read_symbols.go` reads the list of 137exported symbols from a `.a` file, and can be used in a build script to generate 138the symbol list on the fly (by building without prefixing, using 139`read_symbols.go` to construct a symbol list, and then building again with 140prefixing). 141 142This mechanism is under development and may change over time. Please contact the 143BoringSSL maintainers if making use of it. 144 145## Known Limitations on Windows 146 147 * CMake can generate Visual Studio projects, but the generated project files 148 don't have steps for assembling the assembly language source files, so they 149 currently cannot be used to build BoringSSL. 150 151## ARM CPU Capabilities 152 153ARM, unlike Intel, does not have a userspace instruction that allows 154applications to discover the capabilities of the processor. Instead, the 155capability information has to be provided by a combination of compile-time 156information and the operating system. 157 158BoringSSL determines capabilities at compile-time based on `__ARM_NEON`, 159`__ARM_FEATURE_AES`, and other preprocessor symbols defined in 160[Arm C Language Extensions (ACLE)](https://developer.arm.com/architectures/system-architectures/software-standards/acle). 161These values are usually controlled by the `-march` flag. You can also define 162any of the following to enable the corresponding ARM feature, but using the ACLE 163symbols via `-march` is recommended. 164 165 * `OPENSSL_STATIC_ARMCAP_NEON` 166 * `OPENSSL_STATIC_ARMCAP_AES` 167 * `OPENSSL_STATIC_ARMCAP_SHA1` 168 * `OPENSSL_STATIC_ARMCAP_SHA256` 169 * `OPENSSL_STATIC_ARMCAP_PMULL` 170 171The resulting binary will assume all such features are always present. This can 172reduce code size, by allowing the compiler to omit fallbacks. However, if the 173feature is not actually supported at runtime, BoringSSL will likely crash. 174 175BoringSSL will additionally query the operating system at runtime for additional 176features, e.g. with `getauxval` on Linux. This allows a single binary to use 177newer instructions when present, but still function on CPUs without them. But 178some environments don't support runtime queries. If building for those, define 179`OPENSSL_STATIC_ARMCAP` to limit BoringSSL to compile-time capabilities. If not 180defined, the target operating system must be known to BoringSSL. 181 182## Binary Size 183 184The implementations of some algorithms require a trade-off between binary size 185and performance. For instance, BoringSSL's fastest P-256 implementation uses a 186148 KiB pre-computed table. To optimize instead for binary size, pass 187`-DOPENSSL_SMALL=1` to CMake or define the `OPENSSL_SMALL` preprocessor symbol. 188 189# Running Tests 190 191There are two additional dependencies for running tests: 192 193 * The most recent stable version of [Go](https://go.dev/) is required. 194 Note Go is exempt from the five year support window. If not found by CMake, 195 the go executable may be configured explicitly by setting `GO_EXECUTABLE`. 196 197 * On x86_64 Linux, the tests have an optional 198 [libunwind](https://www.nongnu.org/libunwind/) dependency to test the 199 assembly more thoroughly. 200 201There are two sets of tests: the C/C++ tests and the blackbox tests. For former 202are built by Ninja and can be run from the top-level directory with `go run 203util/all_tests.go`. The latter have to be run separately by running `go test` 204from within `ssl/test/runner`. 205 206Both sets of tests may also be run with `ninja -C build run_tests`, but CMake 2073.2 or later is required to avoid Ninja's output buffering. 208 209# Pre-generated Files 210 211If modifying perlasm files, or `util/pregenerate/build.json`, you will need to 212run `go run ./util/pregenerate` to refresh some pre-generated files. To do this, 213you will need a recent version of Perl. 214 215On Windows, [Active State Perl](http://www.activestate.com/activeperl/) has been 216reported to work, as has MSYS Perl. 217[Strawberry Perl](http://strawberryperl.com/) also works but it adds GCC 218to `PATH`, which can confuse some build tools when identifying the compiler 219(removing `C:\Strawberry\c\bin` from `PATH` should resolve any problems). 220 221See (gen/README.md)[./gen/README.md] for more details. 222