Update User Guide

aws · Aug 29, 2024 · 5fed366 · 5fed366
1 parent f6153ec
commit 5fed366
Show file tree

Hide file tree

Showing 2 changed files with 34 additions and 22 deletions.
diff --git 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
@@ -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