yggdrasil/ring
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Reorganize, simplify, and clarify BUILDING.md.

Browse Source
This commit is contained in:
Brian Smith 2023-10-03 11:28:24 -07:00
parent 8387c3953e
commit 38b9bb7de0
1 changed files with 39 additions and 96 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

133
BUILDING.md
View File

@ -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.
Supported Toolchains and Cross-compiling
----------------------------------------
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.
*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
------------------------
@ -31,79 +52,11 @@ 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`.
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\<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.
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