diff --git a/book/src/requirements/windows.md b/book/src/requirements/windows.md index 5cab5e27e15..f550e7f444e 100644 --- a/book/src/requirements/windows.md +++ b/book/src/requirements/windows.md @@ -2,11 +2,15 @@ | Platform | *default* | **fips** | bindgen required? | |---------------------------|--------------------------------------------|-----------------------------------------|-------------------| -| `x86_64-pc-windows-msvc` | C/C++ Compiler, CMake & NASM | C/C++ Compiler, CMake, NASM, Go & Ninja | **_Yes_** | -| `x86_64-pc-windows-gnu` | C/C++ Compiler, CMake & NASM | **Not Supported** | **_Yes_** | -| `aarch64-pc-windows-msvc` | C/C++ Compiler (MSVC's `clang-cl`) & CMake | **Not Supported** | **_Yes_** | +| `x86_64-pc-windows-msvc` | C/C++ Compiler, CMake & \*NASM | C/C++ Compiler, CMake, NASM, Go & Ninja | No | +| `x86_64-pc-windows-gnu` | C/C++ Compiler, CMake & \*NASM | **Not Supported** | No | +| `i686-pc-windows-msvc` | C/C++ Compiler, CMake & \*NASM | **Not Supported** | No | +| `aarch64-pc-windows-msvc` | C/C++ Compiler (MSVC's `clang-cl`) & CMake | **Not Supported** | No | | _Other_ | **Not Supported** | **Not Supported** | N/A | +* The NASM assembler is recommended, but is not required for non-FIPS builds. See the + [Prebuilt NASM objects](#prebuilt-nasm-objects) section below. + ## C/C++ Compiler Use the following instructions to download **Visual Studio Build Tools 2017** or later. @@ -36,6 +40,30 @@ Use the following instructions to download **Visual Studio Build Tools 2017** or 2. Add the NASM installation directory to your PATH * `set PATH="C:\Program Files\NASM;%PATH%"` +### Prebuilt NASM objects + +For Windows x86 and x86-64, the AWS-LC assembly code requires NASM to build. On these platforms, if a NASM assembler is +found during the build process, then it *will* be used to compile the assembly files. However, if a NASM assembler is +not found, then the build may fail except in the following cases: + +* The `AWS_LC_SYS_PREBUILT_NASM` environment variable is found and has a value of "1". +* `AWS_LC_SYS_PREBUILT_NASM` is *not found* in the environment and the "prebuilt-nasm" feature has been enabled. + +If the above cases apply, then our prebuilt NASM objects may be used for the build. To prevent our prebuilt NASM +objects from being used, please set `AWS_LC_SYS_PREBUILT_NASM=0` in your build environment to prevent their use. + +Prebuilt NASM object are not available with the "fips" feature. + +#### About our prebuilt NASM objects + +Our prebuilt NASM objects are generated using the same automation that produces our pregenerated bindings. See our +[GitHub workflow configuration](https://github.com/aws/aws-lc-rs/blob/main/.github/workflows/sys-bindings-generator.yml). +The prebuilt NASM objects are checked into our repository +and are [available for inspection](https://github.com/aws/aws-lc-rs/tree/main/aws-lc-sys/builder/prebuilt-nasm). +For each PR +submitted, [our CI verifies](https://github.com/aws/aws-lc-rs/blob/8fb6869fc7bde92529a5cca40cf79513820984f7/.github/workflows/tests.yml#L209-L241) +that the NASM objects newly built from source match the NASM objects currently in the repository. + ### No-assembly build It is possible to avoid the NASM requirement by setting the `AWS_LC_SYS_NO_ASM`/`AWS_LC_FIPS_SYS_NO_ASM` environment @@ -48,25 +76,6 @@ notes in our [troubleshooting section](../resources.md#troubleshooting). 2. Add the Ninja installation directory to your PATH * `set PATH="C:\ninja\ninja_build;%PATH%"` -## Bindgen - -On most platforms, `bindgen` requires `libclang` or `llvm` package to be installed. -See the [requirements](https://rust-lang.github.io/rust-bindgen/requirements.html) page in -[The bindgen User Guide] for instructions. - -### libclang / LLVM - -1. Download [LLVM Installer](https://github.com/llvm/llvm-project/releases/tag/llvmorg-15.0.6) -2. Execute the installer -3. Update your environment to set `LIBCLANG_PATH` to the bin directory inside LLVM install directory. - * `set LIBCLANG_PATH="C:\Program Files\LLVM\bin"` - -### bindgen-cli - -```shell -cargo install --force --locked bindgen-cli -``` - ## Troubleshooting See our [troubleshooting section](../resources.md#troubleshooting). diff --git a/book/src/resources.md b/book/src/resources.md index c1eefc3ddb8..604f6b3b996 100644 --- a/book/src/resources.md +++ b/book/src/resources.md @@ -20,6 +20,9 @@ future release. Please [contact us] about any bugs you find in our build process be used. This option is only available for unoptimized (i.e., `OPT_LEVEL = "0"` or "debug") builds. **WARNING**: Performance on most platforms is extremely limited by this option. Certain security properties, such as resistance to timing attacks, can only be provided when assembly code is used. +* `AWS_LC_SYS_PREBUILT_NASM` -- value can be set to `1` to *allow* the build to use our prebuilt NASM objects. + The value can be set to `0` to *prevent* our prebuilt NASM objects from being used. See the section on + [Prebuilt NASM objects](requirements/windows.md#prebuilt-nasm-objects) for more information. ## Links