nexmon – Blame information for rev 1

Subversion Repositories:
Rev:
Rev Author Line No. Line
1 office 1 # Building BoringSSL
2  
3 ## Build Prerequisites
4  
5 * [CMake](https://cmake.org/download/) 2.8.8 or later is required.
6  
7 * Perl 5.6.1 or later is required. On Windows,
8 [Active State Perl](http://www.activestate.com/activeperl/) has been
9 reported to work, as has MSYS Perl.
10 [Strawberry Perl](http://strawberryperl.com/) also works but it adds GCC
11 to `PATH`, which can confuse some build tools when identifying the compiler
12 (removing `C:\Strawberry\c\bin` from `PATH` should resolve any problems).
13 If Perl is not found by CMake, it may be configured explicitly by setting
14 `PERL_EXECUTABLE`.
15  
16 * On Windows you currently must use [Ninja](https://ninja-build.org/)
17 to build; on other platforms, it is not required, but recommended, because
18 it makes builds faster.
19  
20 * If you need to build Ninja from source, then a recent version of
21 [Python](https://www.python.org/downloads/) is required (Python 2.7.5 works).
22  
23 * On Windows only, [Yasm](http://yasm.tortall.net/) is required. If not found
24 by CMake, it may be configured explicitly by setting
25 `CMAKE_ASM_NASM_COMPILER`.
26  
27 * A C compiler is required. On Windows, MSVC 14 (Visual Studio 2015) or later
28 with Platform SDK 8.1 or later are supported. Recent versions of GCC (4.8+)
29 and Clang should work on non-Windows platforms, and maybe on Windows too.
30  
31 * [Go](https://golang.org/dl/) is required. If not found by CMake, the go
32 executable may be configured explicitly by setting `GO_EXECUTABLE`.
33  
34 ## Building
35  
36 Using Ninja (note the 'N' is capitalized in the cmake invocation):
37  
38 mkdir build
39 cd build
40 cmake -GNinja ..
41 ninja
42  
43 Using Make (does not work on Windows):
44  
45 mkdir build
46 cd build
47 cmake ..
48 make
49  
50 You usually don't need to run `cmake` again after changing `CMakeLists.txt`
51 files because the build scripts will detect changes to them and rebuild
52 themselves automatically.
53  
54 Note that the default build flags in the top-level `CMakeLists.txt` are for
55 debugging—optimisation isn't enabled. Pass `-DCMAKE_BUILD_TYPE=Release` to
56 `cmake` to configure a release build.
57  
58 If you want to cross-compile then there is an example toolchain file for 32-bit
59 Intel in `util/`. Wipe out the build directory, recreate it and run `cmake` like
60 this:
61  
62 cmake -DCMAKE_TOOLCHAIN_FILE=../util/32-bit-toolchain.cmake -GNinja ..
63  
64 If you want to build as a shared library, pass `-DBUILD_SHARED_LIBS=1`. On
65 Windows, where functions need to be tagged with `dllimport` when coming from a
66 shared library, define `BORINGSSL_SHARED_LIBRARY` in any code which `#include`s
67 the BoringSSL headers.
68  
69 In order to serve environments where code-size is important as well as those
70 where performance is the overriding concern, `OPENSSL_SMALL` can be defined to
71 remove some code that is especially large.
72  
73 See [CMake's documentation](https://cmake.org/cmake/help/v3.4/manual/cmake-variables.7.html)
74 for other variables which may be used to configure the build.
75  
76 ### Building for Android
77  
78 It's possible to build BoringSSL with the Android NDK using CMake. This has
79 been tested with version 10d of the NDK.
80  
81 Unpack the Android NDK somewhere and export `ANDROID_NDK` to point to the
82 directory. Clone https://github.com/taka-no-me/android-cmake into `util/`. Then
83 make a build directory as above and run CMake *twice* like this:
84  
85 cmake -DANDROID_NATIVE_API_LEVEL=android-9 \
86 -DANDROID_ABI=armeabi-v7a \
87 -DCMAKE_TOOLCHAIN_FILE=../util/android-cmake/android.toolchain.cmake \
88 -DANDROID_NATIVE_API_LEVEL=16 \
89 -GNinja ..
90  
91 Once you've run that twice, Ninja should produce Android-compatible binaries.
92 You can replace `armeabi-v7a` in the above with `arm64-v8a` to build aarch64
93 binaries.
94  
95 ## Known Limitations on Windows
96  
97 * Versions of CMake since 3.0.2 have a bug in its Ninja generator that causes
98 yasm to output warnings
99  
100 yasm: warning: can open only one input file, only the last file will be processed
101  
102 These warnings can be safely ignored. The cmake bug is
103 http://www.cmake.org/Bug/view.php?id=15253.
104  
105 * CMake can generate Visual Studio projects, but the generated project files
106 don't have steps for assembling the assembly language source files, so they
107 currently cannot be used to build BoringSSL.
108  
109 ## Embedded ARM
110  
111 ARM, unlike Intel, does not have an instruction that allows applications to
112 discover the capabilities of the processor. Instead, the capability information
113 has to be provided by the operating system somehow.
114  
115 BoringSSL will try to use `getauxval` to discover the capabilities and, failing
116 that, will probe for NEON support by executing a NEON instruction and handling
117 any illegal-instruction signal. But some environments don't support that sort
118 of thing and, for them, it's possible to configure the CPU capabilities
119 at compile time.
120  
121 If you define `OPENSSL_STATIC_ARMCAP` then you can define any of the following
122 to enabling the corresponding ARM feature.
123  
124 * `OPENSSL_STATIC_ARMCAP_NEON` or `__ARM_NEON__` (note that the latter is set by compilers when NEON support is enabled).
125 * `OPENSSL_STATIC_ARMCAP_AES`
126 * `OPENSSL_STATIC_ARMCAP_SHA1`
127 * `OPENSSL_STATIC_ARMCAP_SHA256`
128 * `OPENSSL_STATIC_ARMCAP_PMULL`
129  
130 Note that if a feature is enabled in this way, but not actually supported at
131 run-time, BoringSSL will likely crash.
132  
133 # Running tests
134  
135 There are two sets of tests: the C/C++ tests and the blackbox tests. For former
136 are built by Ninja and can be run from the top-level directory with `go run
137 util/all_tests.go`. The latter have to be run separately by running `go test`
138 from within `ssl/test/runner`.
139  
140 Both sets of tests may also be run with `ninja -C build run_tests`, but CMake
141 3.2 or later is required to avoid Ninja's output buffering.