David Benjamin 4745051fb0 Set a minimum CMake version of 3.0.

CMake 3.0 was released June 10, 2014, just over five years ago. Set the minimum
version to 3.0. This cleans up some Mac workarounds. (CMP0025 was introduced
in 3.0, so setting the minimum version to 3.0 also enables it.)

CMP0025 is important because Clang and Apple Clang use different version
numbers. Prior to CMake 3.0, both read as Clang. Starting CMake 3.0, with
CMP0025 enabled, they read as Clang and AppleClang. Without this, we cannot
sanely version-check clang.

Unfortunately, CMP0025 applies at compiler detection, so if BoringSSL is
imported as a CMake subproject, we are dependent on the root project setting
CMP0025. But if we successfully set a minumum of 3.0, we can reasonably ask
consumers to do the same, which will do so.

Next up: In December, we can raise the version to CMake 3.1, which adds support
for specifying C and C++ language versions in CMake. (Alternatively, Abseil's
minimum version is actually 3.5, so maybe we can update more aggressively
here.)

Update-Note: CMake 2.8 is no longer supported. Update your CMake to the latest
    version if it has not been updated in five years.

Change-Id: I3378567ad7575fc9fac69e05c403d69ea10332e2
Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/36444
Reviewed-by: Adam Langley <agl@google.com>

2019-06-13 16:11:02 +00:00

4.6 KiB

Raw Blame History

Building ring

ring's Rust crate is named ring. See https://crates.io/crates/ring to see what the latest version is and to see how to add a dependency on it to your project.

When hacking on ring itself, you can build it using cargo build and cargo test as usual. ring includes some C, C++, and assembly language components, and its build script (build.rs) builds all those things automatically.

Packaged Builds

When you build ring from its package (e.g. the ones on crates.io), you only need the Rust toolchain and a C/C++ compiler. For Windows targets, the packaged crate contains precompiled object files for the assembly language modules so no macro assembler is required. On other platforms, ring's build script assumes the C/C++ compiler knows how to build .S files (assembly language sources with C preprocessor directives).

Builds directly from Git

If you want to hack on ring then you need to build it directly from its Git repository. In this case, you must also have Perl installed, because the assembly language modules inherited from BoringSSL (inherited from OpenSSL) use Perl as a macro assembly language.

When building from Git for Windows, directories containing yasm.exe and perl.exe must be in %PATH%, where yasm.exe is Yasm 1.3 or later and where perl.exe is recommended to be Strawberry Perl.

Supported Toolchains

ring targets the current stable release of Rust and Cargo. We also verify that the current beta and nightly releases work.

On Windows, ring supports the x86_64-pc-windows-msvc and i686-pc-windows-msvc targets best. These targets require the “Visual C++ Build Tools 2015” package or Visual Studio 2015 Update 3 or later to be installed. Patches to get it working on other variants, including in particular Visual Studio 2017 (#338), Windows ARM platforms, Windows Universal Platform, Windows XP (the v140_xp toolchain; #339), and the -gnu targets (#330) are welcome.

For other platforms, GCC 4.6 or later and Clang 3.5 or later are currently supported best. The build script passes options to the C/C++ compiler that are GCC- and Clang- specific. Pull requests to support other compilers will be considered.

Note in particular that if you are cross-compiling an x86 build on a 64-bit version of Linux, then you need to have the proper gcc-multilibs and g++-multilibs packages or equivalent installed.

If you generate a standalone NDK toolchain in order to compile your project, the wrapper automatically passes flags to the actual compiler to define the __ANDROID_API__ macro. Otherwise, the macro __ANDROID_API__ must be defined with a value of at least 21 on 64-bit targets or 18 on 32-bit targets; e.g. export CFLAGS=-D__ANDROID_API__=21.

Additional Features that are Useful for Development

The use_heap feature enables functionality that uses the heap. This is on by default. Disabling it is useful for code running in kernel space and some embedded applications. For now some RSA, ECDH, and ECDSA signing functionality still uses the heap. This feature will go away once RSA signing is the only feature that uses the heap.

The internal_benches feature enable benchmarks of internal functions. These benchmarks are only useful for people hacking on the implementation of ring. (The benchmarks for the ring API are in the crypto-bench project.)

The slow_tests feature runs additional tests that are too slow to run during a normal edit-compile-test cycle.

The test_logging feature prints out additional logging information during tests, in particular the contents of the test input files, as tests execute. When a test fails, the most recently-logged stuff indicates which test vectors failed. This isn't enabled by default because it uses too much memory on small targets, due to the way that Rust buffers the output until (unless) the test fails. For small (embedded) targets, use cargo test --release --no-run --features=test_logging to build the tests, and then run the tests on the target with ` --nocapture' to see the log.