diff --git a/BUILDING.md b/BUILDING.md index 3555673276..88ad6d8da9 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -1,26 +1,47 @@ 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. - +Supported Toolchains and Cross-compiling +---------------------------------------- + +*ring* currently requires a C (but not C++) toolchain. + +When cross-compiling, a sysroot for the target is usually required too; +[mk/install-build-tools.sh](mk/install-build-tools.sh) documents, in code, +one way to get a working toolchain for various targets. `TARGET_CC` and +`TARGET_AR` (or equivalents) must be set. [mk/cargo.sh](mk/cargo.sh) +documents, in code, one way to successfully cross-compile for various targets. + +Except for Windows x86/x86-64 targets, *ring*'s build script assumes the +C/C++ compiler knows how to build `.S` files (assembly language sources +with C preprocessor directives) for target architectures for which we have +assembly language code (ARM, Aarch64, i686, x86-64). + +For Windows targets, “Build Tools for Visual Studio 2022” (or a higher +edition of Visual Studio, like Community, Standard, or Enterprise). The +“Desktop development with C++” workflow must be installed. Visual Studio +2022 Version 17.5 is supported; earlier versions of Visual Studio may work. + +For Windows ARM64 targets (aarch64-pc-windows-msvc), the Visual Studio Build +Tools “VS 2022 C++ ARM64 build tools” and "clang" components must be installed. +Add Microsoft's provided version of `clang` to `%PATH%`, which will allow the +build to work in GitHub Actions without installing anything: +``` +$env:Path += ";C:\Program Files (x86)\Microsoft Visual Studio\2022\Enterprise\VC\Tools\Llvm\x64\bin" +``` +If you (locally) have “Build Tools for Visual Studio 2022” instead, use: +``` +$env:Path += ";C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Tools\Llvm\x64\bin" +``` 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). - +The *ring* crate released on crates.io needs fewer tools than are required +for building *ring* from Git. Perl isn't required because the output of +the Perl build steps is packaged into the crate. For Windows x86 and x86-64, +the packaged crate contains precompiled object files for the assembly +language modules so no macro assembler. Builds directly from Git ------------------------ @@ -30,80 +51,12 @@ 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`. + primitives (32- and 64- bit Intel, and 32- and 64- bit ARM), Perl must be + installed. Perl must be in `$PATH` or `$PERL_EXECUTABLE` must be set. -* For Windows targets except ARM64, `target/tools/windows/nasm/nasm[.exe]` +* For Windows x86 and x86-64 targets only, `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](.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. - - -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](https://github.com/mstorsjo/llvm-mingw). - -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\\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. - + documented in [mk/install-build-tools.ps1](mk/install-build-tools.ps1). Additional Features that are Useful for Development --------------------------------------------------- @@ -111,13 +64,3 @@ 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. - - -[#321]: https://github.com/briansmith/ring/pull/321 -[#330]: https://github.com/briansmith/ring/issues/330 -[#334]: https://github.com/briansmith/ring/issues/334 -[#336]: https://github.com/briansmith/ring/issues/336 -[#337]: https://github.com/briansmith/ring/issues/337 -[#338]: https://github.com/briansmith/ring/issues/338 -[#339]: https://github.com/briansmith/ring/issues/339 -[#340]: https://github.com/briansmith/ring/issues/340