Source release 14.0.0
This commit is contained in:
John W. Bruce
161
third_party/boringssl/kit/src/BUILDING.md
vendored
Normal file
161
third_party/boringssl/kit/src/BUILDING.md
vendored
Normal file
@@ -0,0 +1,161 @@
|
||||
# Building BoringSSL
|
||||
|
||||
## Build Prerequisites
|
||||
|
||||
* [CMake](https://cmake.org/download/) 2.8.11 or later is required.
|
||||
|
||||
* Perl 5.6.1 or later is required. On Windows,
|
||||
[Active State Perl](http://www.activestate.com/activeperl/) has been
|
||||
reported to work, as has MSYS Perl.
|
||||
[Strawberry Perl](http://strawberryperl.com/) also works but it adds GCC
|
||||
to `PATH`, which can confuse some build tools when identifying the compiler
|
||||
(removing `C:\Strawberry\c\bin` from `PATH` should resolve any problems).
|
||||
If Perl is not found by CMake, it may be configured explicitly by setting
|
||||
`PERL_EXECUTABLE`.
|
||||
|
||||
* On Windows you currently must use [Ninja](https://ninja-build.org/)
|
||||
to build; on other platforms, it is not required, but recommended, because
|
||||
it makes builds faster.
|
||||
|
||||
* If you need to build Ninja from source, then a recent version of
|
||||
[Python](https://www.python.org/downloads/) is required (Python 2.7.5 works).
|
||||
|
||||
* On Windows only, [Yasm](http://yasm.tortall.net/) is required. If not found
|
||||
by CMake, it may be configured explicitly by setting
|
||||
`CMAKE_ASM_NASM_COMPILER`.
|
||||
|
||||
* A C compiler is required. On Windows, MSVC 14 (Visual Studio 2015) or later
|
||||
with Platform SDK 8.1 or later are supported. Recent versions of GCC (4.8+)
|
||||
and Clang should work on non-Windows platforms, and maybe on Windows too.
|
||||
To build the tests, you also need a C++ compiler with C++11 support.
|
||||
|
||||
* [Go](https://golang.org/dl/) is required. If not found by CMake, the go
|
||||
executable may be configured explicitly by setting `GO_EXECUTABLE`.
|
||||
|
||||
* To build the x86 and x86\_64 assembly, your assembler must support AVX2
|
||||
instructions and MOVBE. If using GNU binutils, you must have 2.22 or later
|
||||
|
||||
## Building
|
||||
|
||||
Using Ninja (note the 'N' is capitalized in the cmake invocation):
|
||||
|
||||
mkdir build
|
||||
cd build
|
||||
cmake -GNinja ..
|
||||
ninja
|
||||
|
||||
Using Make (does not work on Windows):
|
||||
|
||||
mkdir build
|
||||
cd build
|
||||
cmake ..
|
||||
make
|
||||
|
||||
You usually don't need to run `cmake` again after changing `CMakeLists.txt`
|
||||
files because the build scripts will detect changes to them and rebuild
|
||||
themselves automatically.
|
||||
|
||||
Note that the default build flags in the top-level `CMakeLists.txt` are for
|
||||
debugging—optimisation isn't enabled. Pass `-DCMAKE_BUILD_TYPE=Release` to
|
||||
`cmake` to configure a release build.
|
||||
|
||||
If you want to cross-compile then there is an example toolchain file for 32-bit
|
||||
Intel in `util/`. Wipe out the build directory, recreate it and run `cmake` like
|
||||
this:
|
||||
|
||||
cmake -DCMAKE_TOOLCHAIN_FILE=../util/32-bit-toolchain.cmake -GNinja ..
|
||||
|
||||
If you want to build as a shared library, pass `-DBUILD_SHARED_LIBS=1`. On
|
||||
Windows, where functions need to be tagged with `dllimport` when coming from a
|
||||
shared library, define `BORINGSSL_SHARED_LIBRARY` in any code which `#include`s
|
||||
the BoringSSL headers.
|
||||
|
||||
In order to serve environments where code-size is important as well as those
|
||||
where performance is the overriding concern, `OPENSSL_SMALL` can be defined to
|
||||
remove some code that is especially large.
|
||||
|
||||
See [CMake's documentation](https://cmake.org/cmake/help/v3.4/manual/cmake-variables.7.html)
|
||||
for other variables which may be used to configure the build.
|
||||
|
||||
### Building for Android
|
||||
|
||||
It's possible to build BoringSSL with the Android NDK using CMake. Recent
|
||||
versions of the NDK include a CMake toolchain file which works with CMake 3.6.0
|
||||
or later. This has been tested with version r16b of the NDK.
|
||||
|
||||
Unpack the Android NDK somewhere and export `ANDROID_NDK` to point to the
|
||||
directory. Then make a build directory as above and run CMake like this:
|
||||
|
||||
cmake -DANDROID_ABI=armeabi-v7a \
|
||||
-DCMAKE_TOOLCHAIN_FILE=${ANDROID_NDK}/build/cmake/android.toolchain.cmake \
|
||||
-DANDROID_NATIVE_API_LEVEL=16 \
|
||||
-GNinja ..
|
||||
|
||||
Once you've run that, Ninja should produce Android-compatible binaries. You
|
||||
can replace `armeabi-v7a` in the above with `arm64-v8a` and use API level 21 or
|
||||
higher to build aarch64 binaries.
|
||||
|
||||
For older NDK versions, BoringSSL ships a third-party CMake toolchain file. Use
|
||||
`../third_party/android-cmake/android.toolchain.cmake` for
|
||||
`CMAKE_TOOLCHAIN_FILE` instead.
|
||||
|
||||
For other options, see the documentation in the toolchain file.
|
||||
|
||||
### Building for iOS
|
||||
|
||||
To build for iOS, pass `-DCMAKE_OSX_SYSROOT=iphoneos` and
|
||||
`-DCMAKE_OSX_ARCHITECTURES=ARCH` to CMake, where `ARCH` is the desired
|
||||
architecture, matching values used in the `-arch` flag in Apple's toolchain.
|
||||
|
||||
Passing multiple architectures for a multiple-architecture build is not
|
||||
supported.
|
||||
|
||||
## Known Limitations on Windows
|
||||
|
||||
* Versions of CMake since 3.0.2 have a bug in its Ninja generator that causes
|
||||
yasm to output warnings
|
||||
|
||||
yasm: warning: can open only one input file, only the last file will be processed
|
||||
|
||||
These warnings can be safely ignored. The cmake bug is
|
||||
http://www.cmake.org/Bug/view.php?id=15253.
|
||||
|
||||
* CMake can generate Visual Studio projects, but the generated project files
|
||||
don't have steps for assembling the assembly language source files, so they
|
||||
currently cannot be used to build BoringSSL.
|
||||
|
||||
## Embedded ARM
|
||||
|
||||
ARM, unlike Intel, does not have an instruction that allows applications to
|
||||
discover the capabilities of the processor. Instead, the capability information
|
||||
has to be provided by the operating system somehow.
|
||||
|
||||
By default, on Linux-based systems, BoringSSL will try to use `getauxval` and
|
||||
`/proc` to discover the capabilities. But some environments don't support that
|
||||
sort of thing and, for them, it's possible to configure the CPU capabilities at
|
||||
compile time.
|
||||
|
||||
On iOS or builds which define `OPENSSL_STATIC_ARMCAP`, features will be
|
||||
determined based on the `__ARM_NEON__` and `__ARM_FEATURE_CRYPTO` preprocessor
|
||||
symbols reported by the compiler. These values are usually controlled by the
|
||||
`-march` flag. You can also define any of the following to enable the
|
||||
corresponding ARM feature.
|
||||
|
||||
* `OPENSSL_STATIC_ARMCAP_NEON`
|
||||
* `OPENSSL_STATIC_ARMCAP_AES`
|
||||
* `OPENSSL_STATIC_ARMCAP_SHA1`
|
||||
* `OPENSSL_STATIC_ARMCAP_SHA256`
|
||||
* `OPENSSL_STATIC_ARMCAP_PMULL`
|
||||
|
||||
Note that if a feature is enabled in this way, but not actually supported at
|
||||
run-time, BoringSSL will likely crash.
|
||||
|
||||
# Running tests
|
||||
|
||||
There are two sets of tests: the C/C++ tests and the blackbox tests. For former
|
||||
are built by Ninja and can be run from the top-level directory with `go run
|
||||
util/all_tests.go`. The latter have to be run separately by running `go test`
|
||||
from within `ssl/test/runner`.
|
||||
|
||||
Both sets of tests may also be run with `ninja -C build run_tests`, but CMake
|
||||
3.2 or later is required to avoid Ninja's output buffering.
|
||||
Reference in New Issue
Block a user