Google Git
Sign in
boringssl / boringssl / HEAD / . / BUILDING.md
blob: e7e7f0e8ad6b0c96e92ad52753dfaab3a81fb909 [file] [log] [blame] [view]
David Benjamin95aaf4a2015-09-03 12:09:36 -0400[diff] [blame]1# Building BoringSSL
2
Hubert Chaoc7b61032023-11-29 16:21:10 +0000[diff] [blame]3## Checking out BoringSSL
4
5 git clone "https://boringssl.googlesource.com/boringssl"
6
David Benjamin95aaf4a2015-09-03 12:09:36 -0400[diff] [blame]7## Build Prerequisites
8
David Benjamin6f9f4cc2018-12-21 16:05:09 -0600[diff] [blame]9The standalone CMake build is primarily intended for developers. If embedding
10BoringSSL into another project with a pre-existing build system, see
David Benjamin90004f02023-11-30 13:10:17 -0500[diff] [blame]11[INCORPORATING.md](./INCORPORATING.md).
David Benjamin95aaf4a2015-09-03 12:09:36 -0400[diff] [blame]12
David Benjamin6f9f4cc2018-12-21 16:05:09 -0600[diff] [blame]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
David Benjamina1843d62023-09-17 10:17:50 -0400[diff] [blame]17 * [CMake](https://cmake.org/download/) 3.12 or later is required.
David Benjamin6f9f4cc2018-12-21 16:05:09 -0600[diff] [blame]18
David Benjamin6f9f4cc2018-12-21 16:05:09 -0600[diff] [blame]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.
David Benjamin95aaf4a2015-09-03 12:09:36 -0400[diff] [blame]23
David Benjamin73d69f42018-11-13 17:49:42 -0600[diff] [blame]24 * On Windows only, [NASM](https://www.nasm.us/) is required. If not found
Brian Smith953cfc82015-10-06 12:51:38 -1000[diff] [blame]25 by CMake, it may be configured explicitly by setting
26 `CMAKE_ASM_NASM_COMPILER`.
David Benjamin95aaf4a2015-09-03 12:09:36 -0400[diff] [blame]27
David Benjamin9ff84912024-12-03 17:00:34 -0500[diff] [blame]28 * Compilers for C11 and C++17, or later, are required. On Windows, MSVC from
David Benjamin2570b282024-10-08 14:54:04 -0400[diff] [blame]29 Visual Studio 2022 or later with Windows 10 SDK 2104 or later are
David Benjaminecb7e9ae2023-09-12 13:41:45 -0400[diff] [blame]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.
David Benjamin95aaf4a2015-09-03 12:09:36 -0400[diff] [blame]33
David Benjamin95aaf4a2015-09-03 12:09:36 -0400[diff] [blame]34## Building
35
36Using Ninja (note the 'N' is capitalized in the cmake invocation):
37
David Benjamin1a5570b2023-04-19 15:38:47 -0400[diff] [blame]38 cmake -GNinja -B build
39 ninja -C build
David Benjamin95aaf4a2015-09-03 12:09:36 -0400[diff] [blame]40
41Using Make (does not work on Windows):
42
David Benjamin1a5570b2023-04-19 15:38:47 -0400[diff] [blame]43 cmake -B build
44 make -C build
David Benjamin95aaf4a2015-09-03 12:09:36 -0400[diff] [blame]45
David Benjaminb96e8162024-01-16 17:07:50 -0500[diff] [blame]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:
David Benjamin95aaf4a2015-09-03 12:09:36 -0400[diff] [blame]49
David Benjaminb96e8162024-01-16 17:07:50 -0500[diff] [blame]50 cmake -GNinja -B build -DCMAKE_BUILD_TYPE=Release
51 ninja -C build
David Benjamin95aaf4a2015-09-03 12:09:36 -0400[diff] [blame]52
53If you want to cross-compile then there is an example toolchain file for 32-bit
David Benjamin1a5570b2023-04-19 15:38:47 -0400[diff] [blame]54Intel in `util/`. Wipe out the build directory, run `cmake` like this:
David Benjamin95aaf4a2015-09-03 12:09:36 -0400[diff] [blame]55
David Benjamin1a5570b2023-04-19 15:38:47 -0400[diff] [blame]56 cmake -B build -DCMAKE_TOOLCHAIN_FILE=../util/32-bit-toolchain.cmake -GNinja
David Benjamin95aaf4a2015-09-03 12:09:36 -0400[diff] [blame]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
Adam Langley2e3c9782015-10-27 08:47:11 -0700[diff] [blame]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
nmittler042e8f72016-02-09 11:25:52 -0800[diff] [blame]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
David Benjaminb96e8162024-01-16 17:07:50 -0500[diff] [blame]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
David Benjamin95aaf4a2015-09-03 12:09:36 -0400[diff] [blame]74### Building for Android
75
David Benjamin52887792017-12-13 18:18:28 -0500[diff] [blame]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.
David Benjamin95aaf4a2015-09-03 12:09:36 -0400[diff] [blame]79
80Unpack the Android NDK somewhere and export `ANDROID_NDK` to point to the
David Benjamin1a5570b2023-04-19 15:38:47 -0400[diff] [blame]81directory. Then run CMake like this:
David Benjamin95aaf4a2015-09-03 12:09:36 -0400[diff] [blame]82
David Benjamin75021b72016-04-28 14:51:36 -0400[diff] [blame]83 cmake -DANDROID_ABI=armeabi-v7a \
David Benjamin92272952023-02-22 11:48:54 -0500[diff] [blame]84 -DANDROID_PLATFORM=android-19 \
David Benjamin52887792017-12-13 18:18:28 -0500[diff] [blame]85 -DCMAKE_TOOLCHAIN_FILE=${ANDROID_NDK}/build/cmake/android.toolchain.cmake \
David Benjamin1a5570b2023-04-19 15:38:47 -0400[diff] [blame]86 -GNinja -B build
David Benjamin95aaf4a2015-09-03 12:09:36 -0400[diff] [blame]87
David Benjamin75021b72016-04-28 14:51:36 -0400[diff] [blame]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
David Benjamin52887792017-12-13 18:18:28 -0500[diff] [blame]92For other options, see the documentation in the toolchain file.
David Benjamin95aaf4a2015-09-03 12:09:36 -0400[diff] [blame]93
David Benjamin9978f0a2019-01-30 16:56:54 -0600[diff] [blame]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
David Benjaminaff72a32017-04-06 23:26:04 -0400[diff] [blame]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
Joshua Liebow-Feeser8c7c6352018-08-26 18:53:36 -0700[diff] [blame]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
David Benjamindfcaadd2024-03-21 15:53:53 +1000[diff] [blame]122the same project to avoid symbol conflicts. Symbol prefixing requires the most
123recent stable version of [Go](https://go.dev/).
Joshua Liebow-Feeser8c7c6352018-08-26 18:53:36 -0700[diff] [blame]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;
David Benjamin1a5570b2023-04-19 15:38:47 -0400[diff] [blame]129comments are supported with `#`). In other words, `cmake -B build
Joshua Liebow-Feeser8c7c6352018-08-26 18:53:36 -0700[diff] [blame]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
Joshua Liebow-Feeser066b1082018-09-17 15:40:24 -0700[diff] [blame]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).
Joshua Liebow-Feeser8c7c6352018-08-26 18:53:36 -0700[diff] [blame]141
142This mechanism is under development and may change over time. Please contact the
143BoringSSL maintainers if making use of it.
144
David Benjamin95aaf4a2015-09-03 12:09:36 -0400[diff] [blame]145## Known Limitations on Windows
146
David Benjamin95aaf4a2015-09-03 12:09:36 -0400[diff] [blame]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
David Benjamin1e156822021-12-27 13:27:22 -0500[diff] [blame]151## ARM CPU Capabilities
Adam Langley6a7cfbe2015-10-16 15:46:46 -0700[diff] [blame]152
David Benjamin1e156822021-12-27 13:27:22 -0500[diff] [blame]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.
Adam Langley6a7cfbe2015-10-16 15:46:46 -0700[diff] [blame]157
David Benjamin846a2272022-01-06 11:12:06 -0500[diff] [blame]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).
David Benjamin1e156822021-12-27 13:27:22 -0500[diff] [blame]161These values are usually controlled by the `-march` flag. You can also define
David Benjamin846a2272022-01-06 11:12:06 -0500[diff] [blame]162any of the following to enable the corresponding ARM feature, but using the ACLE
163symbols via `-march` is recommended.
Adam Langley6a7cfbe2015-10-16 15:46:46 -0700[diff] [blame]164
David Benjamin3b33f3e2017-06-08 16:53:28 -0400[diff] [blame]165 * `OPENSSL_STATIC_ARMCAP_NEON`
Adam Langley6a7cfbe2015-10-16 15:46:46 -0700[diff] [blame]166 * `OPENSSL_STATIC_ARMCAP_AES`
167 * `OPENSSL_STATIC_ARMCAP_SHA1`
168 * `OPENSSL_STATIC_ARMCAP_SHA256`
169 * `OPENSSL_STATIC_ARMCAP_PMULL`
170
David Benjamin1e156822021-12-27 13:27:22 -0500[diff] [blame]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.
Adam Langley6a7cfbe2015-10-16 15:46:46 -0700[diff] [blame]181
David Benjamin6291af42018-03-23 13:49:27 -0400[diff] [blame]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
Adam Langleydc7e9c42015-09-29 15:21:04 -0700[diff] [blame]190
David Benjamindfcaadd2024-03-21 15:53:53 +1000[diff] [blame]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
Adam Langleydc7e9c42015-09-29 15:21:04 -0700[diff] [blame]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
David Benjamin301afaf2015-10-14 21:34:40 -0400[diff] [blame]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.
David Benjaminfe0c91e2024-03-18 15:37:24 +1000[diff] [blame]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.