Skip to content

Latest commit

 

History

History
129 lines (97 loc) · 5.7 KB

BUILDING.md

File metadata and controls

129 lines (97 loc) · 5.7 KB
Raw

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. There are some additional requirements for doing this that do not apply when building from crates.io:

  • For any target for which ring has assembly language implementations of primitives (32- and 64- bit Intel, and 32- and 64-bit ARM), Perl must be installed and in $PATH.

  • For Windows targets except ARM64, target/tools/windows/nasm/nasm[.exe] is used as the assembler. The version to use and how to download it is documented in .github/workflows/ci.yml.

  • For Windows ARM64 target, Clang is used as the C compiler and the assembler. See below "Building for Windows ARM64" section.

Cross Compiling

When you build ring for a target that is different than the one you are using for the build process you need to install the rust tool chain and a C/C++ compiler that can produce binaries for the intended target.

Besides the required dependencies you need to set the environment variables TARGET_CC and TARGET_AR to the full path of the cross-compiler and the cross-archiver respectively.

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. ring now also supports the aarch64-pc-windows-msvc target. For the detailed instructions please see the next section. Patches to get it working on other variants, including in particular Visual Studio 2017 (#338), 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.

Building for Windows ARM64

Windows ARM64 target requires the “Visual C++ Build Tools 2019” package or Visual Studio 2019 or later to be installed. “Desktop development with C++” workflow should be installed, as well as “MSVC v142 - VS 2019 C++ ARM64 build tools” component.

To build ring for Windows ARM64, you will need to install Clang as it is used as the C compiler and the assembler for that platform. You can either use the version of Clang installed by Visual Studio, a standalone version from llvm.org, or a mingw64 version of Clang, for example, from llvm-mingw project.

If you're buiding ring on an ARM64 device like Surface Pro X, please note that llvm.org and llvm-mingw have native ARM64 versions of Clang available. Also, if you're building ring on an ARM64 device, you might want to use aarch64-pc-windows-msvc Rustup toolchain, which can be installed using rustup toolchain add aarch64-pc-windows-msvc.

When building on an ARM64 device, due to a bug in the Visual Studio installer, if you're using rustc version < 1.55 you would need to run cargo build / cargo test commands from x86_arm64 Developer Command Prompt. You can use C:\Program Files (x86)\Microsoft Visual Studio\2019\<edition>\VC\Auxiliary\Build\vcvarsx86_arm64.bat batch script to configure the environment. If you use rustc 1.55 beta or newer, you can run cargo commands without configuring the dev environment beforehand.

Additional Features that are Useful for Development

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 the input test vectors when a test fails.