Reorganize, simplify, and clarify BUILDING.md.
This commit is contained in:
Brian Smith
parent
8387c3953e
commit
38b9bb7de0
135
BUILDING.md
135
BUILDING.md
@ -1,26 +1,47 @@
|
|||||||
Building *ring*
|
Building *ring*
|
||||||
===============
|
===============
|
||||||
|
|
||||||
*ring*'s Rust crate is named `ring`. See https://crates.io/crates/ring to see
|
Supported Toolchains and Cross-compiling
|
||||||
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
|
*ring* currently requires a C (but not C++) toolchain.
|
||||||
`cargo test` as usual. *ring* includes some C, C++, and assembly language
|
|
||||||
components, and its build script (build.rs) builds all those things
|
|
||||||
automatically.
|
|
||||||
|
|
||||||
|
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
|
Packaged Builds
|
||||||
---------------
|
---------------
|
||||||
|
|
||||||
When you build *ring* from its package (e.g. the ones on crates.io), you only
|
The *ring* crate released on crates.io needs fewer tools than are required
|
||||||
need the Rust toolchain and a C/C++ compiler. For Windows targets, the packaged
|
for building *ring* from Git. Perl isn't required because the output of
|
||||||
crate contains precompiled object files for the assembly language modules so no
|
the Perl build steps is packaged into the crate. For Windows x86 and x86-64,
|
||||||
macro assembler is required. On other platforms, *ring*'s build script assumes
|
the packaged crate contains precompiled object files for the assembly
|
||||||
the C/C++ compiler knows how to build `.S` files (assembly language sources
|
language modules so no macro assembler.
|
||||||
with C preprocessor directives).
|
|
||||||
|
|
||||||
|
|
||||||
Builds directly from Git
|
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:
|
apply when building from crates.io:
|
||||||
|
|
||||||
* For any target for which *ring* has assembly language implementations of
|
* 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
|
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
|
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).
|
documented in [mk/install-build-tools.ps1](mk/install-build-tools.ps1).
|
||||||
|
|
||||||
* 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.
|
|
||||||
|
|
||||||
|
|
||||||
Additional Features that are Useful for Development
|
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.
|
a normal edit-compile-test cycle.
|
||||||
|
|
||||||
The `test_logging` feature prints out the input test vectors when a test fails.
|
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
|
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user