Polish newly added docs.
Some general improvements and specific changes to make these documents appear better when hosted [on GitHub Pages](https://google.github.io/iree/GetStarted).
* Use powershell syntax and > to start lines consistently in Windows docs
* Merge Vulkan "troubleshooting" section into earlier steps
* Tweak some phrasing and hyperlink styling
Relates to https://github.com/google/iree/issues/1363
Closes https://github.com/google/iree/pull/1427
COPYBARA_INTEGRATE_REVIEW=https://github.com/google/iree/pull/1427 from ScottTodd:docs-polish 112d139f1f4b072ec780838499e5dd7011629191
PiperOrigin-RevId: 305327559
diff --git a/docs/getting_started_linux_vulkan.md b/docs/getting_started_linux_vulkan.md
index 183904c..506e652 100644
--- a/docs/getting_started_linux_vulkan.md
+++ b/docs/getting_started_linux_vulkan.md
@@ -48,11 +48,12 @@
```shell
# -- CMake --
+$ set VK_LOADER_DEBUG=all
$ cmake --build build/ --target iree_hal_vulkan_dynamic_symbols_test
$ ./build/iree/hal/vulkan/iree_hal_vulkan_dynamic_symbols_test
# -- Bazel --
-$ bazel test iree/hal/vulkan:dynamic_symbols_test
+$ bazel test iree/hal/vulkan:dynamic_symbols_test --test_env=VK_LOADER_DEBUG=all
```
Tests in IREE's HAL "Conformance Test Suite" (CTS) actually exercise the Vulkan
@@ -63,11 +64,12 @@
```shell
# -- CMake --
+$ set VK_LOADER_DEBUG=all
$ cmake --build build/ --target iree_hal_cts_allocator_test
$ ./build/iree/hal/cts/iree_hal_cts_allocator_test
# -- Bazel --
-$ bazel test iree/hal/cts:allocator_test
+$ bazel test iree/hal/cts:allocator_test --test_env=VK_LOADER_DEBUG=all
```
If these tests pass, you can skip down to the next section.
@@ -122,7 +124,6 @@
Build:
```shell
-# -- Bazel --
$ bazel build @vulkan_extensionlayer//:libVkLayer_khronos_timeline_semaphore.so @vulkan_extensionlayer//:VkLayer_khronos_timeline_semaphore_json
```
@@ -130,7 +131,6 @@
path to the built layer:
```shell
-# -- Bazel --
$ VK_LAYER_PATH=$VK_LAYER_PATH:$PWD/bazel-bin/external/vulkan_extensionlayer/
```
@@ -138,7 +138,7 @@
Bazel tests run in a sandbox, which environment variables may be forwarded to
using the `--test_env` flag. A user.bazelrc file supporting each of the steps
-above looks like this (remember to substitute for the {} paths):
+above looks like this (substitute for the `{}` paths):
```
test --test_env="LD_LIBRARY_PATH={PATH_TO_VULKAN_SDK}/x86_64/lib/"
@@ -192,20 +192,6 @@
$ bazel run iree/samples/vulkan:vulkan_inference_gui
```
-## Troubleshooting
-
-If loading Vulkan fails, try running one the test or programs again with
-`VK_LOADER_DEBUG=all` set:
-
-```shell
-# -- CMake --
-$ set VK_LOADER_DEBUG=all
-$ ./build/iree/hal/vulkan/iree_hal_vulkan_dynamic_symbols_test
-
-# -- Bazel --
-$ bazel test iree/hal/vulkan:dynamic_symbols_test --test_env=VK_LOADER_DEBUG=all
-```
-
## What's next?
More documentation coming soon...
diff --git a/docs/getting_started_windows_bazel.md b/docs/getting_started_windows_bazel.md
index 6cf3dab..cbebdd1 100644
--- a/docs/getting_started_windows_bazel.md
+++ b/docs/getting_started_windows_bazel.md
@@ -41,7 +41,7 @@
PowerShell or [cmder](https://cmder.net/)). Setting them through PowerShell
would look like this:
-```shell
+```powershell
> $env:BAZEL_VS = "C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools"
> $env:USE_CLANG_CL = 1
```
@@ -53,7 +53,7 @@
Using your shell of choice (such as PowerShell or [cmder](https://cmder.net/)),
clone the repository and initialize its submodules:
-```shell
+```powershell
> git clone https://github.com/google/iree.git
> cd iree
> git submodule update --init
@@ -67,7 +67,7 @@
Run all core tests:
-```shell
+```powershell
> bazel test -k --config=windows iree/...
```
@@ -91,13 +91,13 @@
Build all of IREE's 'tools' directory:
-```shell
+```powershell
> bazel build iree/tools/...
```
Check out what was built:
-```shell
+```powershell
> dir bazel-bin\iree\tools\
> .\bazel-bin\iree\tools\iree-translate.exe --help
```
@@ -106,7 +106,7 @@
[MLIR file](https://github.com/google/iree/blob/master/iree/tools/test/simple.mlir)
and execute a function in the compiled module:
-```shell
+```powershell
> .\bazel-bin\iree\tools\iree-run-mlir.exe .\iree\tools\test\simple.mlir -input-value="i32=-2" -iree-hal-target-backends=vmla -print-mlir
```
diff --git a/docs/getting_started_windows_cmake.md b/docs/getting_started_windows_cmake.md
index 6df6e7e..9415e87 100644
--- a/docs/getting_started_windows_cmake.md
+++ b/docs/getting_started_windows_cmake.md
@@ -18,7 +18,8 @@
### Install CMake
-Install CMake version >= 3.13 from https://cmake.org/download/.
+Install CMake version >= 3.13 from the
+[downloads page](https://cmake.org/download/).
> Tip:<br>
> Your editor of choice likely has plugins for CMake,
@@ -42,8 +43,8 @@
installation make sure you include "C++ Build Tools"
* Initialize MSVC by running `vcvarsall.bat`:
- ```shell
- $ "C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Auxiliary\Build\vcvars64.bat"
+ ```powershell
+ > "C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Auxiliary\Build\vcvars64.bat"
```
## Clone and Build
@@ -53,10 +54,10 @@
Using your shell of choice (such as PowerShell or [cmder](https://cmder.net/)),
clone the repository and initialize its submodules:
-```shell
-$ git clone https://github.com/google/iree.git
-$ cd iree
-$ git submodule update --init
+```powershell
+> git clone https://github.com/google/iree.git
+> cd iree
+> git submodule update --init
```
> Tip:<br>
@@ -67,8 +68,8 @@
Configure:
-```shell
-$ cmake -G Ninja -B build\ .
+```powershell
+> cmake -G Ninja -B build\ .
```
> Tip:<br>
@@ -78,8 +79,8 @@
Build all targets:
-```shell
-$ cmake --build build\
+```powershell
+> cmake --build build\
```
## What's next?
@@ -88,17 +89,17 @@
Check out the contents of the 'tools' build directory:
-```shell
-$ dir build\iree\tools
-$ .\build\iree\tools\iree-translate.exe --help
+```powershell
+> dir build\iree\tools
+> .\build\iree\tools\iree-translate.exe --help
```
Translate a
[MLIR file](https://github.com/google/iree/blob/master/iree/tools/test/simple.mlir)
and execute a function in the compiled module:
-```shell
-$ .\build\iree\tools\iree-run-mlir.exe .\iree\tools\test\simple.mlir -input-value="i32=-2" -iree-hal-target-backends=vmla -print-mlir
+```powershell
+> .\build\iree\tools\iree-run-mlir.exe .\iree\tools\test\simple.mlir -input-value="i32=-2" -iree-hal-target-backends=vmla -print-mlir
```
### Further Reading
diff --git a/docs/getting_started_windows_vulkan.md b/docs/getting_started_windows_vulkan.md
index 74650e0..bbc6e46 100644
--- a/docs/getting_started_windows_vulkan.md
+++ b/docs/getting_started_windows_vulkan.md
@@ -46,13 +46,14 @@
Run the test:
-```shell
+```powershell
# -- CMake --
-$ cmake --build build\ --target iree_hal_vulkan_dynamic_symbols_test
-$ .\build\iree\hal\vulkan\iree_hal_vulkan_dynamic_symbols_test.exe
+> set VK_LOADER_DEBUG=all
+> cmake --build build\ --target iree_hal_vulkan_dynamic_symbols_test
+> .\build\iree\hal\vulkan\iree_hal_vulkan_dynamic_symbols_test.exe
# -- Bazel --
-$ bazel test iree/hal/vulkan:dynamic_symbols_test
+> bazel test iree/hal/vulkan:dynamic_symbols_test --test_env=VK_LOADER_DEBUG=all
```
Tests in IREE's HAL "Conformance Test Suite" (CTS) actually exercise the Vulkan
@@ -61,13 +62,14 @@
Run the
[allocator test](https://github.com/google/iree/blob/master/iree/hal/cts/allocator_test.cc):
-```shell
+```powershell
# -- CMake --
-$ cmake --build build\ --target iree_hal_cts_allocator_test
-$ .\build\iree\hal\cts\iree_hal_cts_allocator_test.exe
+> set VK_LOADER_DEBUG=all
+> cmake --build build\ --target iree_hal_cts_allocator_test
+> .\build\iree\hal\cts\iree_hal_cts_allocator_test.exe
# -- Bazel --
-$ bazel test iree/hal/cts:allocator_test
+> bazel test iree/hal/cts:allocator_test --test_env=VK_LOADER_DEBUG=all
```
If these tests pass, you can skip down to the next section.
@@ -99,13 +101,13 @@
Pass the flag `-iree-hal-target-backends=vulkan-spirv` to `iree-translate.exe`:
-```shell
+```powershell
# -- CMake --
-$ cmake --build build\ --target iree_tools_iree-translate
-$ .\build\iree\tools\iree-translate.exe -iree-mlir-to-vm-bytecode-module -iree-hal-target-backends=vulkan-spirv .\iree\tools\test\simple.mlir -o .\build\module.fb
+> cmake --build build\ --target iree_tools_iree-translate
+> .\build\iree\tools\iree-translate.exe -iree-mlir-to-vm-bytecode-module -iree-hal-target-backends=vulkan-spirv .\iree\tools\test\simple.mlir -o .\build\module.fb
# -- Bazel --
-$ bazel run iree/tools:iree-translate -- -iree-mlir-to-vm-bytecode-module -iree-hal-target-backends=vulkan-spirv .\iree\tools\test\simple.mlir -o .\build\module.fb
+> bazel run iree/tools:iree-translate -- -iree-mlir-to-vm-bytecode-module -iree-hal-target-backends=vulkan-spirv .\iree\tools\test\simple.mlir -o .\build\module.fb
```
> Tip:<br>
@@ -116,40 +118,26 @@
Pass the flag `-driver=vulkan` to `iree-run-module.exe`:
-```shell
+```powershell
# -- CMake --
-$ cmake --build build\ --target iree_tools_iree-run-module
-$ .\build\iree\tools\iree-run-module.exe -input_file=.\build\module.fb -driver=vulkan -entry_function=abs -inputs="i32=-2"
+> cmake --build build\ --target iree_tools_iree-run-module
+> .\build\iree\tools\iree-run-module.exe -input_file=.\build\module.fb -driver=vulkan -entry_function=abs -inputs="i32=-2"
# -- Bazel --
-$ bazel run iree/tools:iree-run-module -- -input_file=.\build\module.fb -driver=vulkan -entry_function=abs -inputs="i32=-2"
+> bazel run iree/tools:iree-run-module -- -input_file=.\build\module.fb -driver=vulkan -entry_function=abs -inputs="i32=-2"
```
## Running IREE's Vulkan Samples
Install the [Vulkan SDK](https://www.lunarg.com/vulkan-sdk/), then run:
-```shell
+```powershell
# -- CMake --
-$ cmake --build build\ --target iree_samples_vulkan_vulkan_inference_gui
-$ .\build\iree\samples\vulkan\vulkan_inference_gui.exe
+> cmake --build build\ --target iree_samples_vulkan_vulkan_inference_gui
+> .\build\iree\samples\vulkan\vulkan_inference_gui.exe
# -- Bazel --
-$ bazel run iree/samples/vulkan:vulkan_inference_gui
-```
-
-## Troubleshooting
-
-If loading Vulkan fails, try running one the test or programs again with
-`VK_LOADER_DEBUG=all` set:
-
-```shell
-# -- CMake --
-$ set VK_LOADER_DEBUG=all
-$ .\build\iree\hal\vulkan\iree_hal_vulkan_dynamic_symbols_test.exe
-
-# -- Bazel --
-$ bazel test iree/hal/vulkan:dynamic_symbols_test --test_env=VK_LOADER_DEBUG=all
+> bazel run iree/samples/vulkan:vulkan_inference_gui
```
## What's next?
